GraphQL é uma linguagem criada pelo Facebook em 2015 para facilitar a comunicação com API’s, tanto pela interação sistema-sistema quanto pela humano-sistema – neste último caso há uma grande chance desse humano ser um desenvolvedor.

A linguagem foi desenhada para resolver o problema de underfetch (quando vem menos dados do servidor que o necessário, precisando fazer outra(s) requisição(ões) para trazer os dados desejados) – e overfetch (quando vem mais dados que o necessário do servidor). Como efeito colateral positivo, GraphQL também acaba reduzindo o número de requisições feitas a um servidor, já que é possível trazer todas as informações que uma página precisa em apenas uma requisição, ou, como a gente vai falar de agora em diante, query.

GraphQL não foi desenhada como uma solução para ser usada em apenas uma linguagem, mas uma especificação que pode ser implementada em qualquer linguagem, e é isso que vários projetos open-source tem feito.

Vale ressaltar que GraphQL é uma linguagem fortemente tipada, isto é, cada campo de suas consultas precisa ser de um determinado tipo.

Fonte: Blog Localweb

Material complementar:

• Um vídeo contendo uma palestra introdutória sobre GraphQL: Tudo o que você quer saber sobre GraphQL.
• Artigo Conceitos de GraphQL que eu gostaria que alguém tivesse me explicado um ano atrás .

Esse documento mostra o principal bloco de construção do GraphQL, que especifica os dados que você está tentando recuperar.

• Campo: é uma unidade de dado que você está pedindo, ela voltará como um campo no seu JSON de resposta. Note que eles sempre são chamdados de "campos", independente do quão internos na consulta eles apareçam. Um campo na raíz da sua operação funciona da mesma maneira que um aninhado mais interno na sua consulta.
• Argumento: Um conjunto de pares chave-valor anexados a um campo específico. Eles são passados para execução no lado do servidor, e afetam como ele é resolvido. Os argumentos pode ser valores literais, como na consulta abaixo, or variáveis, como no exemplo acima. Note que os argumentos podem aparecer em qualquer campo, até mesmo em campos aninhados mais internamente na operação.

A consulta acima é um formato abreviado do GraphQL, que permite definir uma operação de consulta de uma forma muito concisa. Mas existem três partes opcionais de uma operação GraphQL que ainda não foram utilizadas aqui. Você precisará dessas novas partes se desejar executar algo diferente de uma consulta ou passar variáveis dinâmicas.

Aqui está um exemplo que inclui tudo isso:

• Tipo de Operação: Pode ser query, mutation ou uma subscription. Ela descreve que tipo de operação você está tentanto realizar. Embora todos pareçam semelhantes na linguagem, eles têm modos de execução ligeiramente diferentes em um servidor GraphQL compatível com a especificação.
• Nome da Operação: Por razões de depuração e registro de logs, é aconselhável você dar nomes úteis às suas consultas. Dessa forma, quando alguma coisa errada ocorrer na sua rede ou no servidor GraphQL você pode encontrar facilmente essa consulta no seu repositório através do nome, em vez de tentar decifrar o conteúdo.
• Definição das Variáveis: Quando você envia uma consulta para o servidor GraphQL, você pode ter algunas partes dinâmicas que se alteram entre requisições, enquanto algumas partes do documento parmanecem as mesmas. Essas são as variáveis das sua consulta. Como o GraphQL é estaticamente tipado, ele pode validar para você se está passando as variáveis corretamente. É aqui que você declara os tipos de variáveis que deseja fornecer.

As variáveis são passadas separadamente do documento de consulta de uma maneira específica de transporte, Na implementação atual dos servidores GraphQL, geralmente usa-se JSON. Aque está como uma objeto variável Aqui está como seria uma variável para a consulta acima poderia ser:

Fonte: The anatomy of a GraphQL query

GraphQL Playground é uma ferramenta gráfica, interativa, acessível no seu navegador como uma IDE para o servidor GraphQL. Foi criada pela Prisma e baseada no GraphiQL.

No Servidor de Testes, a ferramenta GraphQL Playground fica habilitada para você criar e testar suas consultas (queries) GraqhQL. Seguindo as boas práticas, no servidor de Produção essa ferramenta é desabilitada.

Alguns elementos importantes da ferramenta GraphQL Playground:

1. Documento GraphQL: aqui você coloca sua query ou mutation. É um campo interativo, com função de auto-completar para os campos disponíveis e validação se a sintaxe está correta.
2. Resposta: Área que o servidor responderá com a retorno da operação executada ou mensagem de erro em caso de falha.
3. Query variables: Local onde se coloca, caso existam, as variáveis da sua operação.
4. HTTP Headers: Cabeçalhos HTTP da sua requisição. No nosso servidor este é o local em que você informará o token da sua aplicação e o token do seu usuário.
5. Docs: Consulta todas as queries e mutations disponíveis no servidor e sua respectiva documentação.
6. Schema: Definição de todos os campos e tipos disponíveis.

Outra ferramenta disponível para visualização das entidades e seus relacionamentos é o GraphQL Voyager. Nela é oferecida uma visão relacional do esquema, navegar interativamente e acessar sua documentação.

A autenticação é controlado por 2 tokens:

• Token de Aplicativo: aplicativo cadastrado e autorizado no Portal da API.
• Token de Usuário: usuário logado em sua Conta Institucional.

A autenticação pode ser acessada via Graphql diretamente na ferramenta interativa playground ou pelo sua aplicativo através de um graphql client.

A Autenticação do aplicativo é realizada fornecendo o appId e appKey fornecidos quando você realiza o cadastro do seu aplicativo no Portal da API. A autenticação do usuário é relizada fornecendo o usuário e senha da Conta Institucional da UFVJM.

Execute a query de Autenticação , serão retornados 2 tokens:

• um token de autenticação válido por 24 horas para o aplicativo
• e um token de usuário válido por 3 horas.

Você deverá acrescentar os cabeçalhos retornados no HTTP Header das consultas que necessitam de autenticação.

Os tokens são do tipo JWT (JSON Web Token), o artigo O que é JSON Web Token? explica o seu funcionamento. De posse dos tokens, você pode utilizar o site jwt.io para decodificá-los e visualizar seu conteúdo.