Общие сведения о GraphQL

Терминология GraphQL

API GraphQL для GitHub представляет собой архитектурный и концептуальный сдвиг в сравнении с REST API GitHub. В справочной документации по API GraphQL вам, скорее всего, встретится новая терминология.

Схема

Схема определяет систему типов API GraphQL. Она описывает полный набор возможных данных (объектов, полей, связей и т. д.), доступных клиенту. Вызовы клиента проверяются и выполняются по схеме. Клиент может найти сведения о схеме путем интроспекции. Схема находится на сервере API GraphQL. Дополнительные сведения см. в разделе Обнаружение API GraphQL.

Поле

Поле — это единица данных, которую можно извлечь из объекта. Как сказано в официальной документации по GraphQL: "Язык запросов GraphQL в основном ориентирован на выбор полей объектов".

В официальной спецификации также говорится о полях следующее:

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

Таким образом, при попытке вернуть поле, которое не является скалярным, проверка схемы выдаст ошибку. Необходимо добавить вложенные поля, чтобы все поля возвращали скалярные значения.

Аргумент

Аргумент — это набор пар "ключ-значение", связанных с определенным полем. Для некоторых полей требуется аргумент. Для изменений в качестве аргумента требуется входной объект.

Внедрение

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

Вот вымышленный пример схемы, определяющей интерфейс X и объект Y:

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

Это означает, что объекту Y требуются те же поля, аргументы и типы возвращаемых значений, что и интерфейсу X, но при этом добавляются и новые поля, характерные для объекта Y. (! означает, что поле является обязательным.)

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

в каждом объекте в разделе Implements перечислены интерфейсы, от которых он наследуется;
в каждом интерфейсе в разделе Implementations перечислены объекты, наследуемые от интерфейса.

Connection

Соединения позволяют запрашивать связанные объекты в рамках одного вызова. С помощью соединений можно использовать один вызов GraphQL вместо нескольких вызовов REST API. Дополнительные сведения см. в разделе Миграция из REST в GraphQL.

Граф можно представить в виде точек, соединенных линиями. Точки — это узлы, а линии — ребра. Соединение определяет связь между узлами.

Microsoft Edge

Ребра представляют соединения между узлами. При запросе соединения вы проходите по ребрам, чтобы достичь узлов. Каждое поле edges содержит поля node и cursor. Курсоры используются для разбиения на страницы. Дополнительные сведения см. в разделе Использование разбиения на страницы в API GraphQL.

Узел

Узел — это универсальный термин для объекта. Обратиться к узлу можно напрямую или через соединение со связанными узлами. Если указан узел (node), не возвращающий скаляр, необходимо включить вложенные поля, чтобы все поля возвращали скалярные значения. Сведения о доступе к идентификаторам узлов через REST API и их использовании в запросах GraphQL см. в разделе "Использование глобальных идентификаторов узлов".

Обнаружение API GraphQL

GraphQL является интроспективным. Это означает, что вы можете запрашивать у схемы GraphQL сведения о ней самой.

Запросите __schema, чтобы получить список всех типов, определенных в схеме, и сведения о каждом из них:
```
query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}
```

Запросите __type, чтобы получить сведения о любом типе:

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

Вы также можете выполнить интроспективный запрос схемы с помощью запроса GET:
```
curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql
```
Примечание. Если получен ответ "message": "Bad credentials" или 401 Unauthorized, убедитесь в том, что используется допустимый токен. Если появится сообщение об ошибке 403 Resource not accessible by personal access token, убедитесь, что ваш fine-grained personal access token предназначен для правильного владельца ресурса. Например, она должна быть нацелена на организацию, которая владеет репозиторием, к которому вы пытаетесь получить доступ.

Результаты возвращаются в формате JSON, поэтому мы рекомендуем выполнить их структурную распечатку, чтобы упростить чтение и поиск. Для этой цели можно использовать такое средство командной строки, как jq, или передать результаты в python -m json.tool.

Кроме того, можно передать тип носителя idl для возврата результатов в формате IDL, который является сжатой версией схемы:
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
http(s)://HOSTNAME/api/graphql
```
Примечание. Интроспективный запрос, вероятно, будет единственным запросом GET, который вы будете выполнять в GraphQL. Если вы передаете текст, методом запроса GraphQL будет POST, будь то запрос или мутация.

Дополнительные сведения о выполнении запросов см. в разделе "Формирование вызовов с помощью GraphQL".

Общие сведения о GraphQL

В этой статье