GraphQL: API intuitiva e flexível para descrever requisitos

28/6/2019
Isac Júnior
Isac Júnior
Front-end Developer

Em busca de constante conhecimento, programa para construir melhores relações e resultados em equipe.

Está sem tempo para ler? Aperte o play para escutar o artigo.

Novas tecnologias

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


1. Desprezo:
Realmente preciso disso?

2. Interesse: Talvez eu deveria verificar o que isso faz.

3. Pânico: Socorro! Eu preciso aprender isto ou ficarei obsoleto.

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

O que é GraphQL?

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.

Ele é 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.

Quando surgiu?

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.

gadgets

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.

separador

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

rest API

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.

endpoints rest API

GraphQL

graphQL

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

<p> CODE: https://gist.github.com/isacjunior/75e5ead67221db2474934c0d86da3180.js</p>

  • 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.

workflow rest API frontend

Aí vai algumas curiosidades

  • Você agora possui apenas um endpoint, não sendo necessário chamar várias requisições.
endpoint
  • 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.
consulta API SWAPI
  • 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.

<p> CODE: https://gist.github.com/isacjunior/5e0327f3c4bcb762818aee62204bd59b.js</p>

<p> CODE: https://gist.github.com/isacjunior/e6fc85e0845a60ee9f884c983455b4d0.js</p>

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

<p> CODE: https://gist.github.com/isacjunior/555a0648da2f2e71305b9df6a9e49534.js</p>

<p> CODE: https://gist.github.com/isacjunior/c26242e2c36801e44bde70b3023044e6.js</p>

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

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. Isso 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 nesse link. 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. 😎

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

Sugestões?

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

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

O que você achou deste conteúdo?
Quer receber nossos conteúdos?
Seu cadastro foi efetuado com sucesso! Enviaremos as novidades no seu email.
Oops! Something went wrong while submitting the form.