Сведения об API GitHub

Сведения об API-интерфейсах GitHub

GitHub предоставляет два API: REST API и API GraphQL. Вы можете взаимодействовать с обоими API с помощью GitHub CLI, curl, официальных библиотек Octokit и сторонних библиотек. Иногда функция может поддерживаться в одном API, но не в другом.

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

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

Выбор API GraphQL

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

Например, чтобы получить имя входа GitHub Enterprise Server десяти ваших подписчиков и имя входа десяти подписчиков каждого из них, можно отправить один запрос, например:

{
  viewer {
    followers(first: 10) {
      nodes {
        login
        followers(first: 10) {
          nodes {
            login
          }
        }
      }
    }
  }
}

Ответ будет объектом JSON, который соответствует структуре запроса.

В отличие от этого, чтобы получить эти же сведения из REST API, необходимо сначала выполнить запрос к GET /user/followers. API будет возвращать имя входа каждого подписчика вместе с другими данными о подписчиках, которые вам не нужны. Затем для каждого подписчика необходимо выполнить запрос к GET /users/{username}/followers. В общей сложности вам потребуется выполнить 11 запросов, чтобы получить те же сведения, которые можно получить из одного запроса GraphQL, и вы получите лишние данные.

Выбор REST API

Так как ИНТЕРФЕЙСы REST API существуют дольше, чем API GraphQL, некоторые разработчики более комфортно работают с REST API. Так как в REST API используются стандартные http-команды и концепции, многие разработчики уже знакомы с основными понятиями использования REST API.

Например, чтобы создать проблему в репозитории octocat/Spoon-Knife , необходимо отправить запрос POST /repos/octocat/Spoon-Knife/issues в с текстом запроса JSON:

{
  "title": "Bug with feature X",
  "body": "If you do A, then B happens"
}

В отличие от этого, чтобы устранить проблему с помощью API GraphQL, необходимо получить идентификатор octocat/Spoon-Knife узла репозитория, а затем отправить запрос, например:

mutation {
  createIssue(
    input: {
      repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky"
      title: "Bug with feature X"
      body: "If you do A, then B happens"}
  ) {
    issue {
      number
      url
    }
  }
}