Desenhar uma API bem é a metade “estrutura” do trabalho. Autenticar e autorizar direito é a metade “acesso”. As duas costumam ser tratadas separadamente, mas uma sem a outra não sustenta nada em produção.

Este é um checklist curto para revisar os dois lados: primeiro o contrato da API, depois as regras de acesso.

1. Comece pelo contrato da API

Em toda review de API, eu começo conferindo estes pontos:

  • Substantivos, não verbos. /getAllCars deveria ser /cars. O verbo já está implícito no método HTTP.
  • Não misture plural e singular entre recursos da mesma API.
  • Sub-recursos deixam a relação explícita na URL: /cars/1/drivers, /cars/1/drivers/2.
  • Idempotência: repetir a mesma operação deveria dar o mesmo resultado. Um POST que cria um recurso novo a cada retry é um problema esperando pra acontecer.
  • Headers não são decoração. Muita informação deveria trafegar por Content-Type, Accept, e não em query string ou body.
  • Facilite o uso com links. Não precisa ser HATEOAS raiz, mas devolver links relacionados no payload economiza uma chamada extra de quem consome.
  • Filtro, ordenação, paginação, seleção de campos. Uma API tem que ser flexível: /cars?color=red, /cars?seats<2. Sem isso, o cliente acaba filtrando client-side o que o servidor já deveria ter filtrado.
  • Versione a API. Quebrar contrato sem versão é forçar todo consumidor a quebrar junto.
  • Use status HTTP corretamente, sempre. 200 pra tudo que “deu certo” e 400 genérico pra tudo que “deu errado” não é design de API, é preguiça.

Isso já é praticamente um checklist comentado: exemplo de request/response ruim de um lado, bom do outro, item por item.

2. Separe autenticação de autorização

OAuth 2.0 é o protocolo padrão da indústria pra autorização — não autenticação. Tratar os dois como sinônimos é um erro comum, e não é só semântica: um token OAuth2 diz o que a aplicação pode fazer em nome de alguém, não confirma quem essa pessoa é.

Um ponto de atenção real, que só aparece depois que o sistema está em produção com tráfego de verdade, é latência. É fácil, por descuido no design, acabar revalidando tokens em duplicidade — uma checagem dupla que ninguém pediu e que custa caro quando multiplicada por milhares de requisições por minuto.

O JWT, por sua vez, não é um token aleatório — tem estrutura: Header, Payload e Signature, cada um codificado e concatenado com pontos. Entender essa anatomia ajuda a debugar problema de autenticação sem depender só de tentativa e erro.

3. Revise a sequência completa

Primeiro o contrato — a API bem desenhada, com regras claras de recurso, filtro e status. Depois quem pode chamar esse contrato, e como — OAuth2 e JWT bem entendidos, sem a confusão entre autenticar e autorizar. O detalhe que separa quem já sofreu com isso em produção de quem só leu a spec é justamente a revalidação duplicada de token: pequena, invisível em dev, cara em escala.