Sua API REST quase nunca foi REST

O problema

Quase toda API web já foi chamada de REST em algum momento.

Mesmo quando ela faz coisas como:

• POST /create-user
• POST /approve-order
• POST /cancel-subscription
• POST /generate-report

Tudo em cima de HTTP. Tudo com JSON. Tudo com status code.

E aí nasce a confusão.

Muita gente trata “REST” como sinônimo de:

• API web
• endpoint HTTP
• JSON indo e voltando

Só que isso apaga uma diferença importante.

Porque uma coisa é usar HTTP como transporte.

Outra é modelar uma interface com semântica orientada a recursos.

Modelo mental

Pense assim:

a maioria das APIs que o mercado chama de REST é, na prática, HTTP+JSON com algumas convenções úteis.

Isso não é uma ofensa.

É só uma descrição mais honesta.

O erro não está em não ser REST “puro”.

O erro está em:

• usar o rótulo para soar sofisticado
• forçar modelagem ruim em nome do rótulo
• perder clareza sobre o tipo de interface que você realmente expôs

Quebrando o problema

REST não é só verbo HTTP com URL bonita

Quando alguém fala REST de forma séria, está falando de uma interface em que:

• recursos são centrais
• a semântica das operações é consistente
• o protocolo HTTP participa do significado
• a conversa fica relativamente previsível para o consumidor

Na prática, isso costuma aparecer como:

• GET /orders/123
• PATCH /users/42
• DELETE /sessions/current

Aqui, o recurso é claro.

Já uma API cheia de comandos explícitos pode até funcionar muito bem.

Mas ela não está necessariamente jogando o mesmo jogo.

O mercado chama muita coisa de REST por convenção, não por precisão

Isso aconteceu porque “REST API” virou rótulo curto para “API HTTP normal”.

É compreensível.

Mas traz um efeito ruim:

o time deixa de distinguir entre:

• interface orientada a recurso
• interface orientada a comando
• interface híbrida

E, quando essa distinção some, o desenho da API piora.

O problema não é impureza. É confusão

Muita discussão sobre REST fica infantil rápido:

• um lado quer pureza teórica
• outro lado despreza qualquer semântica

Os dois erram.

Você não precisa virar fiscal de Richardson Maturity Model para desenhar uma boa API.

Mas também não deveria chamar qualquer coleção de POST /doThing de REST só para encerrar a conversa.

Comando travestido de recurso costuma deixar endpoint esquisito

Esse é um sintoma clássico.

Quando o domínio é dominado por ações, o time tenta forçar um modelo de recurso e cria coisas como:

• POST /orders/123/approve
• POST /orders/123/cancel
• POST /reports/generate

Isso não é automaticamente errado.

Mas é um sinal de que talvez a interface real seja mais próxima de comando do que de manipulação de recurso puro.

E entender isso ajuda a conversar com mais honestidade.

API boa não precisa ganhar discussão filosófica

Ela precisa ser:

• clara
• previsível
• consistente
• evoluível

Se usar convenções REST ajuda nisso, ótimo.

Se forçar REST atrapalha a clareza da fronteira, melhor admitir a natureza da operação e desenhar de forma mais honesta.

Exemplo simples

Imagine uma API de pedidos.

Parte dela é claramente orientada a recurso:

• GET /orders/123
• GET /orders?status=paid
• PATCH /orders/123

Mas parte dela é dominada por ações de negócio:

• aprovar pedido
• capturar pagamento
• reenviar nota fiscal

Se você tentar fingir que tudo é só “atualização de recurso”, pode acabar com endpoints estranhos e contratos pouco claros.

Uma modelagem pragmática pode aceitar uma mistura controlada:

• recursos onde recurso é a abstração certa
• ações explícitas onde comando é a abstração honesta

O importante não é vencer no rótulo.

É não confundir o consumidor.

Erros comuns

• Achar que HTTP + JSON + status code já resolve toda conversa sobre REST.
• Defender pureza teórica e piorar a ergonomia real da API.
• Forçar comandos de negócio para dentro de um modelo de recurso artificial.
• Usar o rótulo REST sem pensar em consistência de contrato.
• Debater nome demais e semântica de menos.

Como um senior pensa

Quem tem mais repertório normalmente não pergunta:

“Isso é REST de verdade?”

Pergunta algo melhor:

“Essa interface está clara sobre o que é recurso, o que é comando e como o consumidor deve pensar nela?”

Essa pergunta é muito mais útil.

Porque sai do performático e vai para o operacional.

Uma interface madura não precisa parecer pura no discurso.

Precisa reduzir ambiguidade.

O que o entrevistador quer ver

Em entrevista, esse tema mede clareza conceitual e pragmatismo.

O avaliador quer ver se você:

• entende que REST é mais do que transporte HTTP
• não cai em purismo desnecessário
• consegue explicar quando recurso faz sentido e quando ação domina a interface
• prioriza contrato e clareza acima de rótulo

Uma resposta forte costuma soar assim:

“Eu diria que a maioria das APIs de mercado chamadas de REST é HTTP+JSON com convenções REST. Isso não é um problema por si só. O problema é não saber se estou modelando recurso ou comando e acabar com uma interface inconsistente. Para mim, a prioridade é clareza de contrato e semântica útil para quem consome.”

O oposto de uma boa API não é “não ser REST puro”. É ser confusa.

Quando o time para de discutir etiqueta e começa a discutir semântica, o desenho melhora bastante.