Сведения об 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
}
}
}