Gravatar

Adriano Dennanni

Leia os últimos artigos publicados por Adriano Dennanni.



GraphQL: como dar ao cliente total controle sobre os dados de uma API
Gravatar publicou em

Programação Tutoriais

Você já deve ter passado por uma situação onde cada um dos seus clientes acessa sua API de maneira diferente, e provavelmente teve que desenvolver rotas e parâmetros específicos para cada um deles. Como se isso não fosse problemático o suficiente, ficou ainda mais complicado lançar uma nova feature ou remover algum resultado ou rota.

Parafraseando o título deste artigo, você se indaga o seguinte: “Como dar ao cliente total controle sobre os dados de uma API?”. A resposta (mais uma vez parafraseando o título) é: utilizando o GraphQL.

GraphQL Logo

GraphQL é uma linguagem de queries criada em 2012 pelo Facebook, num momento em que uma mudança nos apps mobile resultou num grande aumento da quantidade de queries nos servidores. Diante da necessidade de reestruturar toda a maneira pela qual as queries eram feitas, surgiu o GraphQL.

A solução vinda do Facebook é simples: ao invés de existirem diversos endpoints, existe apenas um, capaz de receber queries complexas e devolver uma resposta no formato que o cliente quiser.

Abaixo, temos um exemplo de request e a resposta de uma query GraphQL:

Você pode perceber que a resposta espelha a estrutura do request. Também é interessante destacar que é possível passar parâmetros adicionais, como tamanho da imagem e número máximo de resultados. E isso foi possível sem ter que criar rotas especiais, nem concatenar dezenas de parâmetros nas queries. Mas cima de tudo, vemos que a resposta contém apenas os dados requisitados pelo usuário. Isso resulta num menor consumo de rede e menores tempos de resposta, dependendo da situação.


Exemplo simples

Vamos fazer de conta que temos disponíveis os dados sobre algumas músicas no nosso servidor imaginário. Nele temos informações sobre os artistas, os álbuns e as músicas.

Agora imagine que implementamos uma API REST para esses dados. As rotas disponíveis são as seguintes:

Rota Descrição
/albuns Retorna uma lista de todos os álbuns disponíveis
/albuns/:id Retorna o álbum com o ID especificado
/albuns/:id/songs Retorna todas as músicas do álbum especificado
/artists Retorna uma lista de todos os artistas disponíveis
/artists/:id Retorna o artista especificado
/artists/:id/albuns Retorna os álbuns do artista especificado

Suponha que nós queremos fazer um app Android que mostra todas as músicas de um artista, utilizando a API especificada acima. Bem, nós podemos usar a rota das músicas de um artista… só que essa rota não existe.

Soluções disponíveis para esse nosso problema:

  1. Chamar a rota /artists/:id/albuns com o id do artista e salvar numa lista temporária. Após isso, chamar a rota /albuns/:id/songs para cada álbum armazenado naquela lista temporária, assim conseguindo todas as músicas daquele artista.
     
  2. Implorar para o desenvolvedor da API criar a rota /artist/:id/songs, afinal a solução acima é uma porcaria. Se um artista tem 55 álbuns no seu portfólio, vão ser necessárias 55 requests para obter todas as músicas dele. Se cada request leva 20ms para ser respondida, nesse caso levaríamos 1100ms para obter uma resposta (ignorando eventuais dados no cache). Isso sem falar na memória gasta no seu app por causa dos dados dos álbuns!

E isso não é ruim apenas pelos motivos óbvios. Cada uma dessas rotas deve ser documentada e receber manutenção.

Agora vamos trocar nossa API REST por uma API GraphQL. Abaixo está definido o Schema , ou seja, uma coleção de tipos e definições que espelha nosso modelo de dados:

O schema apenas define como é possível chamar pelos dados através de uma query do GraphQL. Ele não é responsável por fazer as queries no banco de dados, nem sequer determina como as relações dos dados são. Ele simplesmente declara a interface pela qual um usuário pode fazer as queries.

Agora podemos mandar um POST para a rota /graphql contendo o seguinte:

E de resposta, podemos obter algo do tipo:

Mas e a documentação? Ainda temos que detalhar cada uma das possibilidades de pedido de dados? NÃO! Existem ferramentas interativas que te ajudam a documentar a API sem você ter que digitar uma linha a mais de código. A mais utilizada é o GraphiQL, e você pode brincar com a demo dele aqui: http://graphql.org/swapi-graphql/


Considerações Finais

Se sua API é focada em fornecer dados, o GraphQL pode mudar drasticamente sua maneira de desenvolver (para melhor!). Obviamente, cada caso é um caso, mas vale a pena considerar utilizar o GraphQL no seu próximo projeto.

No caso da Infosimples, cada request em nossa API tem como consequência um acesso a um portal web (não acessando diretamente um banco de dados). Assim, o GraphQL não seria tão eficiente, apenas jogando fora informações já obtidas ao invés de mandá-las ao cliente.


Links úteis

Tutorial bem amigável de GraphQL, contendo a maioria das linguagens suportadas: https://www.howtographql.com

Página oficial do GraphQL: http://graphql.org











Leia mais sobre: