Somente POST? Vamos encerrar este debate absurdo sobre design de API

Recentemente, uma discussão sobre se devemos projetar APIs usando "somente POST" chamou minha atenção. Após mergulhar nesse debate, descobri que não apenas a questão sobre a qual as pessoas estão discutindo é sem sentido, mas também expõe o mal-entendido de muitos desenvolvedores sobre a essência do design de API. Hoje, vamos nos aprofundar nas ideias principais do design de API e entender por que esse debate não deveria existir em primeiro lugar.

A confusão do "somente POST"#

Os desenvolvedores que defendem o uso do "somente POST" para substituir as especificações de APIs RESTful claramente não compreenderam o ponto mais importante do design de API. Seus argumentos geralmente incluem:

1. Simplificação do design: Um único método pode lidar com tudo
2. Segurança: Os parâmetros do POST não aparecem na URL
3. Flexibilidade: POST pode enviar qualquer estrutura de dados

À primeira vista, esses argumentos parecem fazer algum sentido. Mas, na verdade, essa visão confunde a escolha dos métodos HTTP com os estilos de design de API, que são questões de níveis diferentes. POST é apenas um método do protocolo HTTP, enquanto REST é um estilo de design de API.

A essência do design de API#

Antes de discutir estilos de API específicos, precisamos entender qual é o objetivo central do design de API. Uma boa API deve ser:

1. Clara e compreensível: Outros desenvolvedores (incluindo você mesmo no futuro) devem ser capazes de entender intuitivamente o propósito de cada endpoint
2. Consistente: Seguir certas especificações para reduzir os custos de aprendizado
3. Extensível: Ser capaz de realizar facilmente controle de versão e expansão de funcionalidades
4. Eficiente: Considerar a eficiência em termos de desempenho e utilização de recursos

API RESTful: Mais do que apenas uma escolha de métodos HTTP#

A API RESTful é apenas um dos muitos estilos de design de API, focada em recursos e operações sobre esses recursos. Vamos pegar um sistema simples de blog como exemplo para ver como a API RESTful é projetada:

1. Obter todos os artigos:

2. Obter um artigo específico:

3. Criar um novo artigo:

4. Atualizar um artigo:

5. Deletar um artigo:

Neste exemplo, podemos ver:

• A API é projetada em torno do recurso "artigo"
• Diferentes métodos HTTP são usados para representar diferentes operações
• A estrutura da URL é clara, indicando o recurso que está sendo operado

Essa abordagem de design torna a API mais intuitiva e autoexplicativa, facilitando para os desenvolvedores entenderem a função de cada endpoint.

RPC: Entendendo o estilo de API por trás do "somente POST"#

O objetivo do estilo de design de API RPC (Chamada de Procedimento Remoto) é fazer com que as chamadas de serviço remoto pareçam tão simples quanto chamar funções locais.

Curiosamente, aqueles que defendem o "somente POST" podem não perceber que estão, na verdade, descrevendo o estilo RPC.

Comparado às APIs RESTful, o RPC foca mais na operação em si do que no recurso. É por isso que as APIs no estilo RPC normalmente usam uma forma "verbo + substantivo", como getProduct(productId) ou createUser(userData).

Em muitas implementações de RPC, todas as operações geralmente são enviadas através de requisições POST para o mesmo endpoint, com a operação específica e os parâmetros especificados no corpo da solicitação. É por isso que a ideia de "somente POST" é, na verdade, mais próxima do RPC do que do REST.

Por exemplo, uma requisição de "obter produto" no estilo RPC baseada em HTTP pode parecer assim:

Frameworks modernos de RPC, como o gRPC, fornecem implementações mais poderosas e eficientes. Vamos usar isso como exemplo para demonstrar o estilo RPC:

Primeiro, definimos o serviço e o formato da mensagem (usando Protocol Buffers):

Depois, usar esse serviço em um cliente Node.js é tão simples quanto chamar uma função local:

Neste exemplo de estilo RPC, podemos ver:

1. A definição do serviço lista claramente todas as operações disponíveis (neste exemplo simplificado, GetArticle e CreateArticle).
2. Cada operação tem tipos de requisição e resposta claramente definidos.
3. O código do cliente parece uma chamada de função assíncrona local, usando await para esperar pelo resultado, o que oculta ainda mais a complexidade da comunicação via rede.
4. Não há necessidade de construir manualmente requisições HTTP ou analisar respostas JSON.

Embora a camada subjacente ainda possa utilizar HTTP/2 como protocolo de transporte, frameworks RPC (como o gRPC) fornecem aos desenvolvedores uma camada de abstração que faz com que as chamadas remotas pareçam e sejam sentidas como chamadas de funções locais.

Portanto, podemos ver que a maioria dos debates sobre "somente POST" e APIs RESTful deveria, essencialmente, ser discussões sobre esses dois estilos de API: REST e RPC. No entanto, o ponto-chave é reconhecer que esses dois estilos têm seus cenários de aplicação e a escolha deve ser baseada nas necessidades específicas do projeto, e não em preferência pessoal.

REST vs RPC: Sem superioridade ou inferioridade absoluta#

Agora que entendemos as diferenças entre REST e RPC, vamos examinar seus respectivos cenários de aplicação:

1. REST é adequado para:
   • Aplicações orientadas a recursos (como sistemas de gerenciamento de conteúdo, plataformas de blog, sites de e-commerce)
   • Cenários que requerem bom suporte a cache (requisições GET são naturalmente armazenáveis em cache)
   • Projetos que querem aproveitar a semântica do HTTP (como usar códigos de status apropriados)
   • APIs públicas que exigem boa capacidade de descoberta e auto-descrição
2. RPC é adequado para:
   • Aplicações orientadas a ações (como operações complexas de processamento de dados, controle de fluxo de trabalho)
   • Sistemas que exigem alta performance e baixa latência (como sistemas de negociação em tempo real)
   • Comunicação entre microsserviços internos (que podem exigir passagem de parâmetros mais flexível)
   • Quando as operações não podem ser simplesmente mapeadas para operações CRUD (Create, Read, Update, Delete)

A escolha do estilo deve ser baseada em suas necessidades específicas. Em alguns casos, você pode até mesmo usar uma mistura desses dois estilos dentro do mesmo sistema para atender às necessidades de diferentes partes.

Conclusão#

1. O coração do design de API reside na clareza, consistência, extensibilidade e eficiência, não na aderência a um método ou estilo específico.
2. Tanto RESTful quanto RPC são paradigmas de design de API maduros. A escolha entre eles deve ser baseada nos requisitos do projeto, não em preferência pessoal.
3. Se você decidir usar "somente POST", então por favor, projete sua API de acordo com o estilo RPC. Assim como RESTful, é uma especificação de API comumente usada na indústria, mas deve ser usada em cenários apropriados.
4. Não se deixe confundir por detalhes técnicos superficiais. O que realmente importa é se sua API pode servir efetivamente seus usuários e necessidades de negócios.
5. Ao projetar APIs, gaste mais tempo pensando sobre seu modelo de recursos, lógica de negócios e necessidades dos usuários, em vez de se preocupar excessivamente sobre qual método HTTP usar.

Vamos direcionar nossa atenção para longe desses argumentos sem sentido e focar em projetar APIs verdadeiramente excelentes. Afinal, a tecnologia existe para resolver problemas, não para criá-los.