Introdução ao GraphQL

Terminologia do GraphQL

A API do GraphQL do GitHub representa uma mudança estrutural e conceitual API REST do GitHub. Provavelmente, você encontrará uma nova terminologia na documentação de referência da API do GraphQL.

Esquema

Um esquema define um sistema de tipos da API do GraphQL. Ele descreve o conjunto completo de dados possíveis (objetos, campos, relações, tudo) que um cliente pode acessar. As chamadas do cliente são validadas e executadas no esquema. Um cliente pode encontrar informações sobre o esquema por meio da introspecção. Um esquema reside no servidor da API do GraphQL. Para obter mais informações, confira "Como descobrir a API do GraphQL".

Campo

Um campo é uma unidade de dados que você pode recuperar de um objeto. Como indica a documentação oficial do GraphQL: "A linguagem de consulta GraphQL trata basicamente da seleção de campos em objetos".

A especificação oficial também traz informações sobre os campos:

Todas as operações do GraphQL devem especificar suas seleções para os campos que retornam valores escalares a fim de garantir uma resposta de forma não ambígua.

Isso significa que se você tentar retornar um campo que não é escalar, a validação do esquema causará um erro. Você deve adicionar subcampos aninhados até que todos os campos retornam escalares.

Argumento

Um argumento é um conjunto de pares de chave-valor anexados a um campo específico. Alguns campos exigem um argumento. As mutações exigem um objeto de entrada como argumento.

Implementação

Um esquema do GraphQL pode usar o termo implementos para definir como um objeto herda de uma interface.

Veja um exemplo inventado de um esquema que define a interface X e o objeto Y:

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

Isso significa que o objeto Y exige os mesmos campos/argumentos/tipos de retorno da interface X, adicionando novos campos específicos ao objeto Y. (O ! significa que o campo é obrigatório).

Na documentação de referência, você descobrirá que:

Cada objeto lista as interfaces das quais ela herda em Implementos.
Cada interface lista os objetos que herdam dele em Implementações.

Conexão

As conexões permitem que você consulte objetos relacionados às consultas como parte da mesma chamada. Com as conexões, você pode usar uma única chamada do GraphQL quando você teria que usar várias chamadas para uma API REST. Para obter mais informações, confira "Fazer a migração de REST para o GraphQL".

É útil imaginar um gráfico: pontos conectados por linhas. Os pontos são nós e as linhas são bordas. Uma conexão define uma relação entre os nós.

Microsoft Edge

As bordas representam conexões entre os nós. Quando você consulta uma conexão, você atravessa suas bordas para chegar a seus nós. Cada campo edges tem um campo node e um campo cursor. Os cursores são usados para paginação. Para obter mais informações, confira "Como usar paginação na API GraphQL".

Nó

Nó é um termo genérico para um objeto. Você pode procurar um nó diretamente pode acessar nós relacionados através de uma conexão. Se você especificar um node que não retorna um escalar, precisará incluir subcampos até que todos os campos retornem escalares. Para obter informações sobre como acessar IDs de nó por meio da API REST e usá-las em consultas GraphQL, confira "Usar IDs de nó globais".

Descobrindo a API do GraphQL

O GraphQL é introspectivo. Isso significa que você pode consultar um esquema do GraphQL para obter informações sobre ele.

Consulte __schema para listar todos os tipos definidos no esquema e obter detalhes sobre cada um:

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

Consulte __type para obter detalhes sobre qualquer tipo:

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

Você também pode executar uma consulta de introspecção do esquema por meio de uma solicitação GET:
```
curl -H "Authorization: bearer TOKEN" https://api.github.com/graphql
```
Observação: se você receber a resposta "message": "Bad credentials" ou 401 Unauthorized, verifique se está usando um token válido. Se você receber o erro 403 com Resource not accessible by personal access token, verifique se o fine-grained personal access token está direcionado ao proprietário correto do recurso. Por exemplo, ele precisa estar direcionado à organização que é o proprietário do repositório que você está tentando acessar.

Os resultados estão no JSON,. Portanto, recomendamos que sejam impressos para facilitar a leitura e pesquisa. Use uma ferramenta de linha de comando como o jq ou encaminhe os resultados a python -m json.tool para essa finalidade.

Como alternativa, você pode transmitir o tipo de mídia idl para retornar os resultados no formato IDL, que é uma versão condensada do esquema:
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
https://api.github.com/graphql
```
Observação: a consulta de introspecção é provavelmente a única solicitação GET que você executará no GraphQL. Se você estiver transmitindo um corpo, o método de solicitação do GraphQL será POST, seja uma consulta ou uma mutação.

Para obter mais informações sobre como executar consultas, confira "Realizar chamadas com o GraphQL".

Introdução ao GraphQL

Neste artigo