Terminologia do GraphQL

A API GitHub GraphQL representa uma mudança arquitetônica e conceitual da API REST 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. Descrição do conjunto completo de dados possíveis (objetos, campos, relacionamentos, tudo) que um cliente pode acessar. As chamadas do cliente são validadas e executadas em relação ao 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. Mutations 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 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, consulte 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.

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, consulte Como usar paginação na API GraphQL.

Node

          _Nó_ é um termo genérico para um objeto. Você pode pesquisar um nó diretamente ou acessar nós relacionados por meio de uma conexão. Se você especificar um `node` que não retorna um [escalar](/graphql/reference/scalars), 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, consulte [AUTOTITLE](/graphql/guides/using-global-node-ids).

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 deve direcionar-se à organização que possui o repositório que você está tentando acessar.

  Os resultados estão no JSON,. Portanto, recomendamos que sejam impressos para facilitar a leitura e pesquisa. Você pode usar uma ferramenta de linha de comando como jq ou redirecionar os resultados para 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, consulte Realizar chamadas com o GraphQL.