GraphQL

Query language para sua API

Novas tecnologias?

A todo momento surgem novas tecnologias e normalmente nossas reações possuem três estágios:

• Desprezo: Realmente preciso disso?
• Interesse: Talvez eu deveria verificar o que isso faz.
• Pânico: Socorro! Eu preciso aprender isto ou ficarei obsoleto.

O segredo para nos mantermos atualizados está em aprender entre o estágio 2 e 3.

O que é?

GraphQL é uma query language para escrevermos nossas APIs. Uma forma para se construir APIs sobre o protocolo HTTP, fornecendo uma sintaxe intuitiva e flexível para descrever os requisitos. O GraphQL, assim como o REST, é uma especificação, uma forma de se buscar os dados do servidor e apresentá-los ao cliente.

O GraphQL é projetado para aplicativos web/móveis (clientes HTTP) poderem fazer chamadas de API buscando os dados que forem convenientes. Existem outras ferramentas capazes de realizar fetch de forma dinâmica, um exemplo é o Falcor do Netflix.

GraphQL surgiu no ano de 2012 e sua primeira aparição foi na React Conf em 2015, sendo aberta à comunidade.

Um ponto que devemos nos atentar aqui é de que não vamos colocar um combate entre REST e GraphQL, demonstrando vantagens e desvantagens. O intuito é mostrar como o GraphQL muda a experiência de como consultamos informações em nossa API, atuando como um auxiliar, junto ao REST, para se construir um middleware.

Como já mencionado acima, iremos analisar um exemplo de middleware, onde iremos consumir os dados de uma API REST. Você é livre para criar sua API em GraphQL consumindo dados da sua base de dados, mas para facilitar o exemplo, vamos utilizar como um middleware.

Características

GraphQL possui três características principais, sendo:

• O cliente é quem especifica exatamente quais dados ele precisa.
• Facilita a agregação de dados de múltiplas fontes.
• Usa um sistema de tipos para descrever dados.

Necessidades distintas

Nos dias atuais, precisamos nos atentar a um detalhe no desenvolvimento de nossas API’s. Existem diferentes aparelhos consumindo sua API e com necessidades diferentes.

Perspectiva do cliente

• Conexão: Pensando em uma aplicação mobile, principalmente em países em desenvolvimento, você deve se preocupar com as condições de conectividade. O cliente paga por isto!
• Dados: under-fetching e over-fetching podem ser prejudiciais e o GraphQL vem pra nos ajudar.
  — under-fetching: Ausência de informações na consulta.
  — over-fetching: Excesso de informações na consulta.

Algumas palavrinhas

• Schema: Tem a função de esclarecer ao nosso programa qual a estrutura da nossa API utilizando nossos tipos.
• Types: É um tipo contendo um conjunto de propriedades para a representação do objeto.
• Query: É o método para realizarmos nossas consultas.
• Mutation: É o método que realizamos nossas adições, alterações, e deleções.
• Subscriptions: É um recurso que permite que um servidor envie dados para seus clientes quando um evento específico acontece.

Cenário

Vamos imaginar um cenário em que tenhamos que expor recursos para a consulta de personagens dos filmes da saga Star Wars.

REST

Em uma API REST você teria dois endpoints, um para realizar a consulta paginada de todos os registros e outro para realizar a consulta por um identificador único.

GET /people
GET /people/:id

GraphQL

GraphQL mudou a forma de como escrevemos nossas API’s. Em GraphQL não precisaríamos identificar nossos recursos por URL’s. Em vez disso, usaríamos nosso schema.

• type People: Temos a representação das informações do personagem a serem consultadas.
• type Query: Temos as possíveis consultas a serem efetuadas.
  - people(id: ID!): People: Query que retorna um personagem a partir de um identificador único não nulo.
  - peoples: [People]: Query que retorna uma lista de personagens.

Como as operações são realizadas?

O front-end envia a consulta ou mutação para a sua API que realiza a consulta no schema contendo as querys e mutations. Tendo o conhecimento do que foi solicitado, os resolvers são solicitados para resolver e encontrar os dados. Lembrando que os resolvers poderiam buscar os dados de um banco de dados.

Curiosidades

• Você agora possui apenas um endpoint, não sendo necessário chamar várias requisições.

https://localhost:3000/graphql

• Só é feita requisições com método POST.
• Agora temos tipos e schemas que estão ligados aos nossos dados. Ao definir o Schema e Types, você automaticamente define sua documentação.

• A estrutura da resposta é equivalente a sua consulta e é o cliente quem define quais dados serão trafegados. Neste exemplo eu solicito apenas o nome do personagem.

• Consulte múltiplos dados em apenas uma requisição.

• Agora temos uma interface chamada GraphQL, ela nos possibilita consultar a documentação, efetuar consultas, mutações e visualizar os resultados.

Devo utilizar GraphQL?

GraphQL nos ajuda a solucionar determinados problemas. Se você não tem tais necessidades, então é necessário verificar se é vantajoso e produtivo trazer uma maior complexidade para o seu ecossistema. Isto irá impactar diretamente os desenvolvedores e a manutenibilidade de sua aplicação.

Code e demo

O projeto mencionado acima se encontra em meu GitHub e a demo também está disponível junto aos links abaixo. A aplicação foi criada utilizando Node.js, TypeScript, GraphQL e Express.js

Críticas são bem-vindas, pois sou apenas um front-end me arriscando no lado negro da força. 😎

GraphiQL — Swapi

isacjunior/graphql-swapi

Você também pode utilizar a documentação oficial do GraphQL e aprender mais sobre.

GraphQL: A query language for APIs.

Sugestões

Se algo dito aqui precisa ser corrigido ou tem algo em que você possa agregar, não deixe de comentar. Precisamos compartilhar conhecimento e enriquecer a nossa comunidade. ❤️

Agradecimento aos colegas Tiago Peres França e Raphael de Souza por ajudar a revisar o texto.