Sobre as APIs de GitHub
GitHub fornece duas APIs: uma API REST e uma API do GraphQL. Você pode interagir com ambas as APIs usando GitHub CLI, curl, as bibliotecas oficiais do Octokit e bibliotecas de terceiros. Ocasionalmente, um recurso pode ter suporte em uma API, mas não na outra.
Você deve usar a API que melhor se alinha às suas necessidades e que você fica mais confortável em usar. Você não precisa usar exclusivamente uma API, em detrimento de outra. As IDs de nó permitem que você alterne entre a API REST e a API do GraphQL. Para saber mais, confira Usar IDs de nó globais.
Este artigo discute os benefícios de cada API. Para obter mais informações sobre a API do GraphQL, confira Sobre a API do GraphQL. Para obter informações sobre a API REST, confira Sobre a API REST.
Escolhendo a API do GraphQL
A API do GraphQL retorna exatamente os dados que você solicita. O GraphQL também retorna os dados em uma estrutura conhecida previamente com base em sua solicitação. Por outro lado, a API REST retorna mais dados do que você solicitou e os retorna em uma estrutura predeterminada. Você também pode realizar o equivalente a várias solicitações de API REST em apenas uma solicitação do GraphQL. A capacidade de fazer menos solicitações e buscar menos dados torna o GraphQL atraente para desenvolvedores de aplicativos móveis.
Por exemplo, para obter o logon do GitHub Enterprise Cloud de dez de seus seguidores e o logon de dez seguidores de cada um dos seus seguidores, você pode enviar apenas uma solicitação como esta:
{
viewer {
followers(first: 10) {
nodes {
login
followers(first: 10) {
nodes {
login
}
}
}
}
}
}
A resposta será um objeto JSON que segue a estrutura de sua solicitação.
Por outro lado, para obter essas mesmas informações da API REST, primeiro você precisará fazer uma solicitação para GET /user/followers. A API retornaria o logon de cada seguidor, juntamente com outros dados sobre os seguidores de que você não precisa. Em seguida, para cada seguidor, você precisaria fazer uma solicitação para GET /users/{username}/followers. No total, você precisaria fazer 11 solicitações para obter as mesmas informações que poderia obter de apenas uma solicitação do GraphQL e receberia dados em excesso.
Escolhendo a API REST
Como as APIs REST existem há mais tempo do que as APIs do GraphQL, alguns desenvolvedores estão mais confortáveis com o primeiro tipo. Como as APIs REST usam verbos e conceitos HTTP padrão, muitos desenvolvedores já estão familiarizados com os conceitos básicos para utilizá-las.
Por exemplo, para criar um problema no repositório octocat/Spoon-Knife, você precisaria enviar uma solicitação para POST /repos/octocat/Spoon-Knife/issues com um corpo de solicitação JSON:
{
"title": "Bug with feature X",
"body": "If you do A, then B happens"
}
Por outro lado, para criar um problema usando a API do GraphQL, você precisaria obter a ID do nó do repositório octocat/Spoon-Knife e, em seguida, enviar uma solicitação como:
mutation {
createIssue(
input: {
repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky"
title: "Bug with feature X"
body: "If you do A, then B happens"}
) {
issue {
number
url
}
}
}