Explorando a API GraphQL do GitHub com React

Uma nova maneira de se conectar a APIs. Aprenda como integrar essa tecnologia na sua aplicação React e a utilizar o GraphQL Playground.

Image for post
Image for post

O GraphQL é uma tecnologia que está cada vez mais comuns no universo do desenvolvimento. Ela surgiu como uma nova alternativa ao padrão REST para construção e consumo de APIs. O GraphQL é uma query language, isso quer dizer que ela nos trás uma visão mais declarativa na hora de buscar os dados do nosso backend. O foco está mais em "o que" será buscado, e não em "como" esses dados serão buscados. Esse é o mesmo paradigma que encontramos por exemplo no SQL quando queremos realizar buscas no banco de dados.

Com o GraphQL você define explicitamente os dados que deseja receber, e casos eles se relacionem de alguma maneira, consegue também buscar esses dados já relacionados.

Para ver o potencial dessa tecnologia seria legal se tivéssemos uma API GraphQL que fosse de fácil acesso e muito bem documentada. Para nossa sorte o GitHub decidiu adotar o GraphQL como padrão na versão 4 de sua API e possuem uma excelente documentação. Se você não conhece a API do GitHub, ela permite que busquemos informações sobre repositórios, usuários, issues, dentre muitas outras coisas. É muito útil em casos onde você quer explorar alguma tecnologia e não quer ter o trabalho de criar mocks ou uma API completa do zero.

O que você vai aprender aqui?

  • Algumas vantagens de APIs GraphQL sobre APIs REST.
  • Como se conectar a API GraphQL do GitHub.
  • Como utilizar o GraphQL PlayGround: Ferramenta visual para consumir APIs no estilo Insomnia e Postman.
  • Como conectar sua aplicação React a uma API GraphQL.
  • Como realizar queries (data fetch) e renderizar componentes baseado nesses dados.

Aprofundando o Problema

Se você em algum momento precisou consumir alguma API na sua aplicação Web ou Mobile, provavelmente consumiu uma API REST. E se precisou de dados um pouco mais complexos se deparou realizando diversas request e utilizando diversos endpoints. Para exemplificar vamos utilizar a API do GitHub e fazer um fetch para buscar informações sobre um determinado repositório.

Se além disso quisermos trazer informações sobre as issues, precisaríamos realizar duas chamadas a API:

No código acima, muito provavelmente o repository e o issues possuem dados que você sequer cogitou usar, afinal eles tem que atender a todas as demandas possíveis, pois não existe uma maneira simples em APIs REST de você especificar os dados que precisa.

Foi para resolver esse e alguns outros desafios que o GitHub resolveu construir a v4 da sua API utilizando a especificação GraphQL.

The ability to define precisely the data you want — and only the data you want — is a powerful advantage over the REST API v3 endpoints. GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify.

Mas e agora como eu começo a consumir uma API GraphQL?

Como já foi dito mais acima, o GraphQL é uma especificação, então para que possamos integra-lo na nossa aplicação, precisamos de uma implementação dessa especificação. O Facebook, criador do GraphQL, implementou um client chamado Relay para que aplicações React possam consumir APIs GraphQL.

Outro implementação muito popular é a Apollo GraphQL. É ela que iremos utilizar aqui para conectar nossa aplicação React com a API GraphQL do GitHub.

Fazendo sua primeira chamada com o GraphQL Playground

Quando queremos consumir APIs REST de maneira rápida, para fins de testes ou exploração, por exemplo, utilizamos algumas ferramentas como Insomnina ou Postman. Então para que inicialmente possamos conhecer um pouco do poder do GraphQL antes mesmo de integra-lo a nossa aplicação React, vamos utilizar uma ferramenta conhecida como GraphQL Playground. Aqui irei utilizar a versão Desktop, mas também está disponível em versão Web.

Na API GraphQL temos apenas um endpoint, que geralmente é configurado no início do projeto. O endpoint do GitHub para sua API GraphQL é: https://api.github.com/graphql.

Assim que abrimos o GraphQL Playground ele nos pede para criarmos um Workspace, podendo ser local ou através de um endpoint (nosso caso). Selecionamos então URL ENDPOINT e colocamos o endpoint do GitHub como na imagem a seguir:

Image for post
Image for post
Conectando API do GitHub

Eis então que nos deparamos com nosso primeiro problema: Autenticação. Diferente da API REST do GitHub que nos permite fazer até 60 requests por hora sem estarmos autenticado, a API do GraphQL nos exige um token para validar a conexão.

Image for post
Image for post
Sem Conexão :(

Gerando Token para se Conectar a API do GitHub

Para nossa sorte, gerar esse token é bem simples, basta ter uma conta no GitHub. No seu perfil vá em Settings, na aba lateral vá em Developer settings e em seguida Personal access tokens. Prontinho, aqui você consegue gerar o token com as devidas permissões. Se quiser um passo a passo mais detalhado basta seguir esse help do próprio GitHub:

Agora que já possui o token basta coloca-lo ho header das suas chamadas. No GraphQL Playground basta adicionar o seguinte na aba HTTP Header:

Substituir YOUR_TOKEN pelo seu token

Agora basta clicar no botão de Play no centro da tela, e seu PlayGround deve está maios ou menos assim:

Image for post
Image for post

Repare que na lateral direito eu cliquei na aba DOCS, ela será seu principal guia na construção das suas chamadas a API. Ali você pode ver todas as suas QUERIES (busca de dados) e MUTATIONS (Alteração e criação de dados). Essas são as duas principais operação que você irá fazer na construção da sua aplicação e que substituirão os tradicionais http methods GET, POST, PUT e DELETE. Se voce quiser saber mais profundamente como cada uma dessas operações funciona, a documentação do GraphQL é um excelente ponto de partida, pois possui diversos exemplos bem detalhados e de fácil compreensão (ainda mais para os fãs de Star Wars). Então vai fundo e que a Força esteja com você!

Apresentado os devidos conceitos e ferramentas, estamos prontos para realizar nossa primeira Query. E aqui vem mais uma das vantagens da GraphQL, como ele é orientado a schema, ao construir a API os desenvolvedores estão construindo sua própria documentação, o que permite ao client dessa API ter exatamente todas as operação que pode realizar, bem como todos os filtros, parâmetros e dados que elas ter permitem requisitar. Além é claro de viabilizar o uso do autocomplete em ferramentas visuais e editores de código.

Every GraphQL service defines a set of types which completely describe the set of possible data you can query on that service. Then, when queries come in, they are validated and executed against that schema.

Buscando um Repositório no GitHub

Vamos montar nossa query que irá substituir o GET utilizado para buscar um repositório. Criamos uma query chamada GetRepository (o nome é você quem escolhe) e dentro dela começamos a construir a busca, nesse caso passamos os parâmetros owner e name assim como os dados que queremos (id, nameWithOwner, description, url).

Lembrando que todos os dados disponíveis estão documentados no schema. A seguir temos a nossa resposta, exatamente o que especificamos.

Uma comparação lado a lado no GraphQL Playground:

Image for post
Image for post

Se quiser mais detalhes de como montei essa query utilizando o autocomplete do Playground, gravei um vídeo bem rápido (24 segundos) dessa operação. Reparem que o Playground, graças a schema e a docs, nos sugere os parâmetros e dados que podemos utilizar. Para sugestões basta utilizar o atalho control + space.

Integrando o GraphQL na aplicação React

Beleza, agora vamos ver como fazer essa chamada de dentro das nossas aplicações React. Como foi dito anteriormente, utilizaremos a lib Apollo. Ela possui um excelente documentação e acompanha muito bem a evolução tanto do GraphQL quanto do próprio React, disponibilizando hooks para realizarmos as operações.

Seguindo a documentação do Apollo precisamos dos seguintes packages:

yarn add apollo-boost @apollo/react-hooks graphql

Para que toda a nossa aplicação tenha acesso as funcionalidades do Apollo, vamos encapsular nosso componente raiz (App) com um Provider fornecido pela biblioteca. Também precisamos configurar nosso client, conceitualmente a mesma coisa que fizemos no GraphQL Playground, pra isso precisamos novamente de duas informações: o endpoint e o token.

E é isso, sua aplicação React está pronta para realizar as maravilhas do GraphQL, utilizando como base a nossa a biblioteca Apollo. Simples né? Bom, existes diversas outras configurações que podemos fazer, mas o apollo-boost abstrai boa parte delas para a gente e na maioria dos casos é suficiente para nosso projeto. Agora estamos prontos para utilizar os hooks dentro dos nosso componentes para realizar queries e mutations.

Se quiser mais detalhes sobre as configuração recomendo dar uma olhada na documentação, o Get started deles é muito bom.

Realizando Queries nos Componentes

Para fazermos uma query utilizaremos um hooks chamado useQuery. Ele faz a chamada para a API assim que o componente é renderizado, retornando 3 informação: loading, error e data. Essa abordagem trás para nós um ganho de produtividade muito significativo, pois em diversas situações precisamos de alguma maneira indicar para o usuário ou para a nossa própria aplicação se algum dado está sendo carregado ou obtivemos algum erro. Em uma fetch feito numa API REST, nós teríamos que por exemplo, criar e gerenciar variáveis de estado para o loading e error :

Com o useQuery podemos renderizar o nosso componente baseado no valor atual do loading, error e data:

Reparem que acima na utilização do useQuery eu passei dois parâmetros para esse hooks. O primeiro é a própria query, montada com o auxílio do gql, o segundo é o objeto variables, que correspondem exatamente aos parâmetro necessários para realizar a query.

Buscando um Repositório e suas Issues

Como foi dito anteriormente uma das maiores vantagens do GraphQL é conseguir buscar dados complexos, no que diz respeito a relacionamento de entendidas, de uma maneira simples e intuitiva.

Par buscar informações sobre um repositório, assim como suas issues, na API REST, teríamos que fazer duas requests, além disso essas requisições trariam uma série de dados que não estamos interessados no momento.

Fazendo uma espécie de exercício mental, pense em como esses dados são armazenados no banco de dados. Muito provavelmente existe alguma referencia na tabela "Issue" sobre seu "Repository", ou vice versa. Com o GraphQL nós tomamos consciência desses relacionamentos graças ao schema e podemos utiliza-lo nas queries para trazer essas informações agrupadas e realizarmos apenas uma chamada.

Nesse caso das Issues, o Github nos permite buscar outras informações, como no exemplo da query acima onde trazemos o totalCount, as issues propriamente ditas estão dentro do nodes que é basicamente um array de "Issue", onde entre outras propriedades temos id, title e url.

Agora podemos usar essa query no nosso componente e nosso data possui todos os dados que especificamos a respeitos do repositório e das issues.

Considerações Finais

Acredito que o GraphQL seja uma tecnologia que veio para ficar, e se tornará cada vez mais popular nos próximos anos (ou você acha q o GitHub apostou nele atoa?). Mas apesar disso creio que tenha uma curva de adoção um pouco mais lenta do que outras tecnologias de maneira geral, isso devido ao simples fato de que é preciso adotá-la nas duas pontas: backend e frontend. Se tiver curiosidade sobre como essa tecnologia surgiu, recomendo assistir o documentário, feito no estilo Netflix pela HoneyPot, com os engenheiros do Facebook que criaram o GraphQL.

Em breve pretendo escrever mais sobre o GraphQL e a a biblioteca Apollo, existem muitas coisas que não abordamos aqui, como as mutations, subscriptions e políticas de cache (essa parte é fenomenal). Se ficou com alguma dúvida ou gostaria de dar alguma sugestão para os próximos artigos só deixar ai nos comentários. Abraços e até a próxima!

Written by

A Brazilian software engineer resolving problems with React Native, TypeScript, GraphQL, and some other nice technologies.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store