APIs e Microsserviços

9 abr, 2018

Conheça o GraphiQL – O editor gráfico de consultas GraphQL

Publicidade

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.

Interface do GraphiQL

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.

Documentação da API disponível para consulta

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.

Referências