Skip to main content

Comparando a API REST do GitHub e a API GraphQL

Saiba mais sobre as APIs dos GitHub para estender e personalizar sua experiência no GitHub.

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 obter mais informações, 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
    }
  }
}