API GraphQL x API Restful: fornecendo dados de maneira flexível
Em um breve resumo, entenderemos como surgiu a API GraphQL e como sua maneira flexível de expor dados pode nos oferecer vantagens sobre uma API Rest em certas situações.
Era uma vez…
Se olharmos os motivos que levaram à criação da famosa API’s Rest, veremos que eles estão perdendo algum sentido quando olhamos para os sistemas atuais.
Basicamente, uma API Rest foi criada com o objetivo de disponibilizar os dados de um sistema, permitindo que aplicativos clientes os consumam.
Esses aplicativos de consumidor podem ser os mais variados e não ter absolutamente nada em comum entre si. Em certos casos, o sistema do fornecedor pode nem se importar com quem está consumindo sua API.
Dessa forma, os aplicativos cliente devem gerenciar com os terminais disponíveis e se contentar com os dados deles.
Você já imaginou o Google criando em uma de suas APIs Rest um endpoint específico para seu aplicativo Android? E mais: retornando exatamente os dados de que você precisa para configurar sua view (nem mais nem menos informações) apenas para economizar largura de banda quando seu aplicativo, e somente ele, iria baixar essas informações? Claro que não!
Na vida real, as solicitações de descanso de APIs de terceiros (principalmente para montagem de front-end) sofrerão com mais frequência: Seja com a quantidade excessiva de informações ou com a falta delas. E se a situação for a última, será necessário fazer mais solicitações para terminais diferentes, a fim de recuperar todos os dados importantes para a montagem da visualização.
Esses terminais foram feitos sob medida (daí o termo customizado) especificamente para atender a um (s) cliente (s) específico (s).
Desta forma, a eficiência das solicitações dos clientes aumentou, pois as API’s traziam tudo o que era necessário em uma única solicitação, economizando chamadas consecutivas para outros endpoints e economizando na transmissão de dados devido ao envio apenas de informações relevantes.
“… Muitos aplicativos de servidor começaram a criar os famosos terminais personalizados para fornecer dados completos.”
O problema é que esse “contorno” tem alguns efeitos colaterais que podem ser desagradáveis.
Imagine um cenário no qual você tem vários tipos de aplicativos cliente front-end consumindo a mesma API Rest, como android, iOS e web. Para cada plataforma mencionada, você terá uma apresentação de dados diferente.
E para piorar, podemos dizer que neste caso, dentro de cada plataforma, você também terá uma diferenciação das informações levando em consideração o tamanho da tela do dispositivo que está realizando o acesso.
Abaixo está um exemplo hipotético de endpoints para listar usuários:
/application-context/api/v3/android/smartphone/users
/application-context/api/v2/android/tablet/users
/application-context/api/v2/ios/smartphone/users
/application-context/api/v2/ios/tablet/users
/application-context/api/v1/web/desktop-large-screen/users
/application-context/api/v1/web/desktop-small-screen/users
/application-context/api/v1/web/smartphone/users
/application-context/api/v1/web/tablet/users
O controle de versão, manutenção e programação desses terminais seria bastante complicado.
Além do fato de que toda vez que houvesse uma mudança no layout ou nos dados apresentados, a API também precisaria ser atualizada.
Esses problemas começaram a incomodar a equipe de desenvolvimento do Facebook em 2012.
Foi então que decidiram inventar uma nova forma de construção de API’s, dando origem à API GraphQL (apresentada posteriormente na ReactConf 2015).
API GraphQL
A API GraphQL foi criada para permitir que o cliente API tenha mais controle sobre as informações que deseja ou não obter, ou mais precisamente, a estrutura do resultado de uma solicitação realizada.
Portanto, não precisamos mais consertar o molde das respostas nas APIs. Graças a essa flexibilidade adquirida, apenas dois endpoints serão usados em nossa API, a saber: consultas e mutação.
As ações que essas consultas / mutações podem realizar serão definidas ao criar nossa API GraphQL (através de esquemas) onde podemos informar os “métodos” que estarão disponíveis aos clientes.
Queries
É o endpoint responsável por trazer as informações. Nele, especificamos os campos que queremos de uma determinada entidade e também os argumentos de pesquisa.
Exemplo de uma solicitação que retornará o nome do herói de nossa API GraphQL (sem argumentos):
Exemplo com argumentos:
Mutations
É o nó de extremidade responsável por executar as operações de criação, atualização ou remoção de dados.
Assim como nas consultas, podemos especificar a estrutura de dados que desejamos receber como resultado dessas operações. Isso pode ser útil para saber o status de uma entidade após realizar as operações necessárias.
No exemplo a seguir, estamos adicionando um canal com o nome “basquete” e queremos como resultado dessa operação uma estrutura de dados que nos diga os campos “id” e “nome” do canal que acabamos de adicionar, para apresentar em nossa visão da extremidade dianteira.
Se a criação da entidade resultar em erro e não for concluída, “id” e “name” chegarão vazios.
Podemos ver que a liberdade de um cliente GraphQL API é muito maior.
Isso até aumenta o desempenho das equipes de desenvolvimento, já que o desenvolvedor de front-end não terá que esperar que o desenvolvedor de back-end crie um ponto de extremidade personalizado para que ele possa montar sua visão e validar os testes de ponta a ponta.
Forças
- Maior flexibilidade do lado do cliente: Esta é sem dúvida a principal vantagem, pois permite ao cliente informar quais os dados que deseja receber. Isso permite que os mais diversos clientes recuperem apenas os dados relevantes para suas necessidades.
- Menor consumo de largura de banda: Ao trazer apenas os dados necessários, evita que dados irrelevantes sejam baixados do servidor, economizando largura de banda e aumentando a eficiência na solicitação de recursos.
- Equipes mais independentes: os desenvolvedores de front-end têm mais liberdade para realizar suas tarefas, não ficando à mercê da criação de endpoints personalizados pelos desenvolvedores de back-end.
- Mais fácil de dimensionar e manter: elimina a necessidade de atualizar a API sempre que dados diferentes precisam ser consumidos por um cliente.
Fraquesas
- Tratamento de erros: como não há URLs separados para cada recurso, um erro 404 que seria facilmente detectado usando uma API Rest, não estará aqui. Para identificar um erro como este, devemos, por exemplo, definir um campo “status_code” no corpo da solicitação como parte da estrutura a ser preenchida como uma resposta pela API GraphQL.
- Cache HTTP: Além disso, por ter apenas dois URLs, o uso de cache HTTP não é viável.
- Semântica e previsibilidade de uso da API: O desenvolvimento de métodos de acesso tanto para mutações quanto para consultas deve ser muito bem definido e consistente para que possam ser acessados pelo cliente de forma intuitiva. Por exemplo: se um método de acesso para excluir um usuário através da API é denominado “removeUser”, para excluir um produto ele deve ser “removeProduct” e não “deleteProduct”.
Projeto experimental
Recentemente, criei um projeto para fins educacionais usando a API GraphQL e o disponibilizei no GitHub. Explora o uso dessa tecnologia por meio de um sistema simples.
Também elaborei um guia de como usar e testar a API (em inglês e português). As ferramentas utilizadas no projeto foram:
- GraphQL for Java;
- Spring Boot + Spring Data (frameworks);
- PostgreSQL version 10.3 (database);
- Flyway (for database versioning).
Link: https://github.com/Augustomesquita/my-api-graphql
Conclusão
Obviamente, a API GraphQL não é uma bala de prata. Gosto muito de comparar madeira: se você vier a um marceneiro e perguntar se ele prefere martelo ou serra, ele vai rir, porque embora ambos sejam ferramentas, cada um tem um propósito diferente.
O mesmo se aplica aqui. Embora API Rest e GraphQL API sejam ferramentas, cada uma será mais eficiente se usada na situação certa e quando necessário.
Para se aprofundar no assunto, sugiro que você acesse o site oficial (do qual vários conceitos importantes foram retirados para a criação deste artigo): https://graphql.org/.
Bem, esse foi um breve resumo sobre a API GraphQL. Se gostou deste post, deixe um like e compartilhe com seus amigos! Isso nos inspirará a continuar trazendo conteúdo como este para você.
Vejo você em breve!
