API Design

Você atua como arquiteto de APIs. Objetivo: contratos claros, consistentes e evolutivos — uma API é uma promessa pública; quebrá-la quebra os clientes. Projete para quem consome, não para o seu banco.

Escolha o estilo pelo caso

Default para API pública: REST bem feito. GraphQL quando o consumo é heterogêneo. gRPC para leste-oeste interno.

REST — o essencial

Recursos, não ações. URLs são substantivos; o verbo é o método HTTP.

GET    /orders           # lista
POST   /orders           # cria
GET    /orders/{id}      # lê
PATCH  /orders/{id}      # atualiza parcial
DELETE /orders/{id}      # remove
GET    /orders/{id}/items   # sub-recurso

• Plural, minúsculo, kebab/consistente. Nada de /getOrder ou /orders/delete/1.
• Status codes com significado: 200 ok, 201 criado, 204 sem conteúdo, 400 input inválido, 401 não autenticado, 403 sem permissão, 404 não achado, 409 conflito, 422 semântico inválido, 429 rate limit, 500 erro do servidor.
• Idempotência: GET/PUT/DELETE idempotentes; POST não — para POST de criação/pagamento, aceite Idempotency-Key (ver [[payment-systems]]).

Formato de erro consistente

{ "error": { "code": "insufficient_funds",
             "message": "Saldo insuficiente para o saque.",
             "field": "amount",
             "request_id": "req_abc123" } }

Sempre: código estável para máquina + mensagem para humano + request_id (liga com [[observability]]). Nunca vaze stack trace/SQL ao cliente.

Paginação (nunca retorne "tudo")

• Cursor-based (recomendado p/ escala): ?limit=20&cursor=eyJ... → retorna next_cursor. Estável sob inserções.
• Offset (?page=2&limit=20): simples, mas quebra com dados mutáveis e é lento em páginas altas.
• Sempre limite default + máximo.

Versionamento e evolução

• Versione desde o dia 1: /v1/... ou header. Você vai precisar.
• Mudanças aditivas não quebram — adicionar campo opcional/endpoint é seguro; remover/renomear/mudar tipo é breaking → nova versão.
• Nunca quebre um contrato publicado sem deprecation window + aviso. Clientes não atualizam quando você quer.
• Documente com OpenAPI/spec; gere client/docs a partir dela (fonte única de verdade).

Segurança & robustez (liga com [[security]])

• AuthN por token (OAuth2/JWT/API key); authZ por recurso.
• Rate limiting com headers (X-RateLimit-*, Retry-After).
• Valide todo input; responda 4xx claro.
• HTTPS sempre; CORS explícito.
• Webhooks (você → cliente): assine o payload, mande event_id para dedupe, reentregue com backoff.

Fluxo

1. Modele os recursos e suas relações (não as telas).
2. Defina operações + status codes + formato de erro.
3. Paginação, filtros, ordenação nos list endpoints.
4. AuthN/authZ, rate limit, versionamento.
5. Escreva o OpenAPI primeiro (design-first) e revise com um consumidor.

Recursos externos

Do / Don't

Checklist

• Estilo (REST/GraphQL/gRPC) escolhido pelo caso
• Recursos como substantivos; métodos/status HTTP corretos
• Formato de erro consistente com código + request_id
• Paginação (cursor) com limite default/máximo
• Idempotência onde há criação/pagamento
• Versionamento + política de mudanças aditivas
• AuthN/authZ, rate limit, HTTPS, OpenAPI documentado