GraphQL

С помощью GraphQL предметная область моделируется в виде графа путём определения схемы: в ней задаются различные типы узлов и их отношения друг с другом^[10].

Система типов определяет, какие данные могут быть запрошены через API. Совокупность таких возможностей называется схемой сервиса, а клиенты могут использовать схему для отправки предсказуемых запросов^[11].

Корневой тип схемы, по умолчанию Query, содержит все доступные для запроса поля. Другие типы определяют объекты и поля, которые сервер GraphQL может вернуть. Выделяются базовые типы, так называемые скалярные, для представления строк, чисел, идентификаторов и др.

Поля по умолчанию допускают отсутствие значения (nullable), а восклицательный знак после типа делает поле обязательным (not-null). Для обозначения списка тип оборачивается в квадратные скобки, например: authors: [String]^[12]:

type Query {
  currentUser: User
}

type User {
  id: ID!
  name: String!
}

Запрос в GraphQL явно определяет форму (структуру) требуемых данных.

query CurrentUser {
  currentUser {
    name
    age
  }
}

После проверки и выполнения сервером данные возвращаются в той же структуре.

{
  "currentUser": {
    "name": "John Doe",
    "age": 23
  }
}

Мутация в GraphQL позволяет создавать, изменять или удалять данные. Обычно при мутациях используются переменные, чтобы параметры операции поступали с клиента. В мутации также указывается структура возвращаемого результата.

mutation CreateUser($name: String!, $age: Int!) {
  createUser(userName: $name, age: $age) {
    name
    age
  }
}

Переменные передаются объектом, содержащим поля с соответствующими именами:

{
  "name": "Han Solo",
  "age": 42
}

После выполнения операции сервер возвращает данные в описанной структуре:

{
  "data": {
    "createUser": {
      "name": "Han Solo",
      "age": 42
    }
  }
}

GraphQL также поддерживает режим подписки: сервер может отправлять клиенту актуальные изменения данных. Как и в других операциях, клиент определяет структуру необходимых данных при каждом обновлении.

subscription {
  newPerson {
    name
    age
  }
}

При выполнении соответствующей мутации подписанные клиенты получают новые данные в указанном формате:

{
  "newPerson": {
    "name": "Jane",
    "age": 23
  }
}

Хотя ничто не мешает внедрять версионирование GraphQL API так же, как и других API, сам подход GraphQL акцентируется на непрерывном развитии схемы без выделения версий^[13].

Встроенная директива @deprecated используется для пометки устаревших полей и значений в определении схемы^[12].

GraphQL возвращает только явно запрошенные поля, поэтому новые возможности легко добавлять новыми типами или полями, избегая критических изменений. На практике сложился подход его использования без версионности^[13].

GraphQL не предоставляет полноценного графового языка запросов, как SPARQL, или диалектов SQL с поддержкой транзитивного замыкания. Например, интерфейс GraphQL, возвращающий родителей персоны, не позволит получить в одном запросе всех предков.