# Introdução ao GraphQL Aprenda a terminologia e os conceitos úteis para usar a API GitHub GraphQL. ## 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](/pt/enterprise-server@3.22/graphql) 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](https://graphql.org/learn/validation/) e [executadas](https://graphql.org/learn/execution/) em relação ao esquema. Um cliente pode encontrar informações sobre o esquema por meio da [introspecção](#discovering-the-graphql-api). Um esquema reside no servidor da API do GraphQL. Para obter mais informações, confira [Como descobrir a API do GraphQL](#discovering-the-graphql-api). ## Campo Um campo é uma unidade de dados que você pode recuperar de um objeto. Como indica a [documentação oficial do GraphQL](https://graphql.org/learn/schema/): "A linguagem de consulta GraphQL trata basicamente da seleção de campos em objetos". A [especificação oficial](https://spec.graphql.org/June2018/#sec-Language.Fields) 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](/pt/enterprise-server@3.22/graphql/guides/forming-calls-with-graphql#about-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](/pt/enterprise-server@3.22/graphql/reference/interfaces). Veja um exemplo inventado de um esquema que define a interface `X` e o objeto `Y`: ```graphql 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](/pt/enterprise-server@3.22/graphql/reference/objects) lista as interfaces *das quais ela herda* em **Implementos**. * Cada [interface](/pt/enterprise-server@3.22/graphql/reference/interfaces) 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](/pt/enterprise-server@3.22/graphql/guides/migrating-from-rest-to-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](/pt/enterprise-server@3.22/graphql/guides/using-pagination-in-the-graphql-api). ## Node *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](/pt/enterprise-server@3.22/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, confira [Usar IDs de nó globais](/pt/enterprise-server@3.22/graphql/guides/using-global-node-ids). ## Descobrindo a API do GraphQL O GraphQL é [introspectivo](https://graphql.org/learn/introspection/). 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: ```graphql query { __schema { types { name kind description fields { name } } } } ``` * Consulte `__type` para obter detalhes sobre qualquer tipo: ```graphql 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`: ```shell curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql ``` > \[!NOTE] > 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](https://stedolan.github.io/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: ```shell $ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \ http(s)://HOSTNAME/api/graphql ``` > \[!NOTE] > 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](/pt/enterprise-server@3.22/graphql/guides/forming-calls-with-graphql).