Сравнение REST API GitHub и API GraphQL

Сведения об API-интерфейсах %% данных variables.product.company_short %}

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.

Выбор 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
    }
  }
}