O GraphQL – desenvolvido pelo time de engenheiros do Facebook – surgiu em 2012 como uma linguagem de consulta de dados, de código aberto e fortemente tipada para APIs em tempo de execução. Diferente do que alguns pensam, o GraphQL é uma especificação. Isso que significa que ele não está vinculado a nenhum tipo de banco de dados ou linguagem. Quer usá-lo com JavaScript? Ótimo. Java? Perfeito. C#? Não vejo porque não. Há uma série de implementações em várias linguagens que são suportadas oficialmente, clique aqui para ver elas.
O grande diferencial é que essa linguagem funciona com um sistema de tipos onde é possível criar um schema para a API. Com ele, podemos obter uma validação das consultas feitas pela aplicação para saber o que foi requisitado e retornar exatamente o que foi requisitado. Nada mais e nada menos. Em termos práticos, isso significa que podemos requisitar para um endpoint somente os campos que precisamos de dada resposta. Por exemplo, se tivéssemos um endpoint /user/:id que devolve um JSON com uma série de informações, como:
{ "nome": "João", "sobrenome": "da Silva", "idade": 38, "CPF": "999.999.999-06", "sexo": "masculino" }
Agora imagine que na tela que precisamos consumir essa API, só precisaremos do CPF. Parece meio inútil ter que receber todo o resto das informações, não é? Esse é um exemplo simples, mas imagine um API REST de um serviço web real, geralmente são arquivos JSON bem extensos. É aí que o GraphQL entrar para resolver esse problema. Neste artigo, há uma série de informações sobre o funcionamento do GraphQL. Aqui, vamos nos concentrar em como podemos aprendê-lo, testando visualmente.
Conheça o GraphiQL
Em um primeiro momento, o GraphQL pode ser bem confuso – digo por experiência própria. A primeira vez que o vi em uma apresentação, achei bastante complicado. No entanto, como tudo na programação, quando você começa a testar e ver seu funcionamento, as coisas se tornam muito mais fáceis de entender, e foi pra isso que o GraphiQL foi criado.
O GraphiQL, como a própria descrição oficial do repositório diz, é uma ferramenta online para escrever, validar e testar consultas do GraphQL. O projeto é código aberto e está hospedado no GitHub, onde possui mais de 1000 commits, 5408 estrelas e 450 forks. No momento em que este artigo está sendo escrito, está na versão v0.11.11 (lançada em dezembro do ano passado). Para quem já conhece o Postman, ele opera de forma bem semelhante.
O GraphiQL nos permite validar qualquer tipo de API feita com GraphQL. Ela faz isso através de várias funcionalidades interessantes, como:
- Realce de sintaxe (Syntax highlighting)
- Auto complete
- Gerenciamento de erros e relatórios em tempo real
- Gerenciamento e execução de queries e resultados
- E muito mais!
Sua instalação é bem simples, basta criar tem um projeto em Node e importar o pacote com o comando:
npm install --save graphiql // ou então yarn add graphiql
No entanto, para fins demonstrativos, utilizaremos a sua demo online. Nesta versão, temos acesso a todas as funcionalidades da ferramenta em cima de uma API do Star Wars, o que nos possibilita brincar com queries que trás informações sobre o seu vasto universo.
A primeira coisa que devemos reparar é que a interface é dividida em três partes, sendo iniciada com somente duas delas a vista (a terceira é o painel de Query Variables, que fica escondido no final da tela). Do lado esquerdo, é onde escrevemos as nossas queries em GraphQL. Para saber o que é possível consultar, podemos clicar no botão Docs no canto superior direito. Lá, há uma descrição de todas as queries, campos e tipos disponíveis.
Para mostrar o seu funcionamento, vamos fazer uma consulta simples. Vamos criar uma query que nos retorna o nome de todos os filmes do Star Wars. Para isso, usaremos a seguinte query:
{ allFilms { films { title } } }
Experimente escrevê-la no console da ferramenta (ao invés de apenas copiar e colar), pois você verá o funcionamento do auto complete. Ao terminar, clique no botão play ou então use o atalho Ctrl + Enter.
Bem legal, né? Podemos apertar o Ctrl + Espaço para usar o Auto complete e verificar quais outros campos podemos consultar como, por exemplo: director, episodeID, producers, releaseDate, entre outras.
E sabe o mais bacana de tudo? O GraphiQL mantém todas as suas consultas disponíveis na URL, então se você quiser ver este resultado, basta clicar aqui.
Conclusão
Se você está estudando o funcionamento do GraphQL, ou quer testar a sua API de forma visual e com as facilidades de um sistema de auto complete, realce de sintaxe a afins, o GraphiQL foi feito pra você.
Neste artigo mostrei somente o funcionamento da ferramenta e não sua configuração. Se for do seu interesse, deixe nos comentários que eu faço uma continuação, onde montaremos uma API juntos para ser consumida no GraphiQL.