Design de APIs RESTful e GraphQL

Uma API (Application Programming Interface) é um conjunto de protocolos e ferramentas que permite que diferentes sistemas de software interajam entre si. Ela age como uma ponte, permitindo que aplicações possam requisitar e trocar dados ou executar operações sem conhecer as implementações internas de cada sistema. APIs definem regras claras de quais dados podem ser acessados, como devem estar formatados e quais ações são permitidas, garantindo interações consistentes e confiaveis entre os componentes. Isso torna APIs uma parte essecial da grande maioria dos softwares modernos.

As APIs podem vir de diversos tipos, incluindo na forma de APIs web, que permitem a comunicação entre os sistemas por meio da internet, usando protocolos como HTTP. Dentre as APIs web, destaca-se as APIs RESTful como sendo a mais popular, devido ao seu foco na simplicidade, escalabilidade e o uso de formatos conhecidos como JSON ou XML. Outros tipos de APIs populares incluem GraphQL, SOAP e gRPC que possuem vantagens significativas em situações especificas no lugar de APIs REST.

RESTful APIs:

Uma API é considerada RESTful se seguir os princípios REST (REpresentational State Transfer), que nada mais são do que princípios arquiteturais que impõem condições em como sistemas web devem se comunicar utilizando do protocolo HTTP.

As APIs REST são orientadas a recursos, ou seja, separam-se as requisições com base na entidade, recurso, presente no servidor e indicados no final da URL de requisição como /products ou /users.

Para executar suas ações, as APIs REST utilizam-se da feature built-in de métodos dentro do protocolo HTTP. Dentre eles, destacam-se os seguintes:

GET: Recupera informações sobre um recurso;
POST: Envia dados para criar ou processar um recurso*;
PUT: Substitui ou cria um recurso;
DELETE: Remove um recurso;
PATCH: Atualiza parte da informação de um recurso;

*Não idempotente: Se a ação for repetida, o resultado pode não ser o mesmo.

Princípios REST:

Interface Uniforme: O servidor deve transferir informação de uma maneira padronizada. O formato do recurso apresentado pela API pode ser diferente de sua representação interna.
Ausência de Estado: Qualquer requisição por parte do cliente é independente de requisições prévias. As requisições podem ser feitas em qualquer ordem pois são isoladas das outras.
Sistema em Camadas: Permite que o sistema conecte em intermediários autorizados entre o cliente e o servidor e ainda receber uma resposta do servidor. O próprio serviodr pode passar a requisição para outros servidores. As camadas devem ficar invisiveis para os clientes.
Cacheabilidade: APIs REST devem suportar cache, ou seja, armazenamento de algumas respostas no cliente ou em um intermediário para melhorar o tempo de resposta

Benefícios:

Escalabilidade: Sistemas que implementam APIs RESTful podem escalar eficientemente, pois REST otimiza interações cliente-servidor. A ausência de estados remove cargas de trabalho do servidor, pois não precisa reter dados das requisições dos clientes. E um bom mecanismo de cache permite eliminar completa ou parcialmente a necessidade de interações entre cliente-servidor.
Flexibilidade: Serviços web REST suportam uma separação total entre cliente e servidor. Eles simplificam e desacoplam componentes do servidor para que possam evoluir independentemente, além de poderem utilizar de tecnologias e plataformas totalmente diferentes.
Independência: APIs REST são independentes da tecnologia usada. Você pode escrever a aplicação do cliente ou do servidor em qualquer linguagem de programação sem ter que alterar qualquer aspecto do design da sua API.

Alguns outros tópicos:

Paginação:

Algumas respostas são grandes demais para serem encaminhadas em uma unica resposta, para lidar com isso, existem técnicas de paginação que permitem o servidor retornar somente parte da resposta por vez e o cliente enviar outras requisições solicitando as partes restantes dos dados desejados. Dentre as técnicas de paginação, seguem algumas delas:

Paginação Offset: desloca-se um número especifico de itens (offset) do conjunto de dados total de resposta para buscar no máximo um número x de itens, especificado pelo valor do parâmetro 'limit' . Ex: /users?limit=20&offset=340
Paginação Keyset: Buscam-se sempre os valores mais recentes, limitados pelo valor do parâmetro 'limit', para buscar resultados anteriores, filtram-se os valores pela data do valor mais recente recebido da requisição anterior. Ex: /users?limit=20&created:lte:2019-01-20T00:00:00
Paginação Seek: Utiliza-se de ids unicos para filtrar os valores e buscar os próximos. Ex: /users?limit=20&after_id=80

Status de Respostas:

Toda resposta do protocolo HTTP deve incluir um código de status, ele representa o resultado da requisição enviada. O status é representado por um número de 3 dígitos e cada código válido possui um significado diferente, porém podemos agrupa-los seguindo o número da centena:

1XX: Utilizado para informar que a requisição ainda está sendo processada ou algum próximo passo que o cliente deve realizar;
2XX: Códigos que indicam sucesso na requisição;
3XX: Indicação de redirecionamento, seja pela ausência do recurso, da rota ou de alterações no recurso;
4XX: Indica um erro por parte do cliente;
5XX: Indica um erro por parte do servidor;

GraphQL APIs

GraphQL é uma linguagem de busca para APIs e um runtime para executar essas consultas com base em um sistema rígido de tipos. Oferece uma alternativa mais flexível e eficiente ao REST, permitindo que o cliente defina as informações que precisa, ao invés de receber todas predefinidas pelo servidor.

Ao contrário das APIs REST, que são baseadas em recursos e endpoints fixos, as APIs GraphQL operam sobre um único endpoint, geralmente exposto via HTTP. O cliente envia uma consulta (query) que descreve os dados desejados, e o servidor retorna exatamente esses dados, nada mais, nada menos.

Principais Características:

Consultas Flexíveis: Com o GraphQL, o cliente pode especificar os campos exatos de que precisa em uma única consulta. Isso reduz a quantidade de dados transferidos e evita problemas comuns de sobrecarga de dados (over-fetching) ou falta de dados (under-fetching), comuns em APIs REST.
Mutations: São usadas para criar, atualizar ou excluir dados no servidor. Semelhante ao POST, PUT ou DELETE no REST, mas permitindo que o cliente defina exatamente quais dados deseja retornar após a mutação.
Subscriptions: Permitem que o cliente receba atualizações em tempo real sobre os dados, útil para implementações de sistemas reativos.
Tipagem Forte: GraphQL usa um sistema de tipos rigoroso, onde a estrutura da consulta e da resposta é definida previamente no esquema da API. Isso permite que o cliente saiba exatamente o que pode esperar da API.

Benefícios:

Eficiência: O cliente tem total controle sobre os dados que deseja, evitando o envio de informações desnecessárias ou incompletas.
Desacoplamento: Como o cliente pode definir exatamente as consultas, ele se torna menos dependente de mudanças no lado do servidor. Isso facilita a evolução independente entre ambos.
Introspectividade: O esquema GraphQL pode ser inspecionado em tempo real, permitindo que desenvolvedores descubram quais dados estão disponíveis e como interagir com a API sem a necessidade de documentação separada.

RESTful APIs:

Princípios REST:

Benefícios:

Alguns outros tópicos:

Paginação:

Status de Respostas:

GraphQL APIs

Principais Características:

Benefícios:

Referências