Design de APIs

Modelar recursos e escolher o verbo HTTP

Caminho = recurso (substantivo plural), método = ação (GET/POST/PUT/PATCH/DELETE). Ação não-CRUD: modele como sub-recurso de estado ou PATCH no status; evite verbo no path por reflexo.

Status codes que dizem a verdade

200+erro no corpo engana caches/monitoramento. 400 malformado, 401 sem auth, 403 sem permissão, 404 não existe, 409 conflito de estado, 422 inválido semanticamente. 5xx = culpa do servidor.

Versionar uma API sem quebrar cliente

Versão no path (visível) ou header (limpo). Quebra: remover/renomear campo, mudar tipo/semântica, exigir novo parâmetro. Não quebra: adicionar campo/endpoint/param opcional. Evolua aditivo.

Paginação offset x cursor

Offset: simples, permite pular pra página N, mas lento em profundidade e instável sob escrita. Cursor: rápido e estável (usa índice), mas sem salto pra página arbitrária. Feed → cursor.

Idempotency-Key num POST

Cliente manda `Idempotency-Key` única; servidor processa uma vez, guarda o resultado pela chave e devolve o mesmo resultado em retries. Escrita chave+operação tem que ser atômica.

Um formato de erro consistente

Formato único: `code` estável pra máquina, `message` humana pra debug, `fields` por campo quando for validação, opcional `traceId`. Não vaze stack/SQL; não use a mensagem como contrato.

REST é um espectro, não um checklist

Modelo de Richardson: nível 0 (RPC) → 1 (recursos) → 2 (verbos+status) → 3 (HATEOAS). APIs reais vivem no nível 2; HATEOAS quase ninguém faz. Consistência importa mais que o checklist.

O problema N+1 nos resolvers de GraphQL

Resolver de campo aninhado roda 1x por item pai → N queries. DataLoader adia, agrupa todos os ids num `IN (...)`, deduplica e cacheia por request.

Por que caching e rate limiting são mais difíceis em GraphQL

Cache HTTP é por URL+GET; GraphQL é 1 endpoint via POST → cache vai pra aplicação (normalizado no cliente, persisted queries). Rate limit vira análise de custo/complexidade da query, não contagem.

Over/underfetching: o que GraphQL resolve e o que ele custa

Cliente pede só os campos que quer, aninhado, numa resposta — mata over e underfetching. Em troca: servidor perde controle do que roda (precisa limite de custo) e erros parciais.

Schema-first x code-first

Schema-first: SDL é a fonte da verdade, resolvers têm que casar (contrato legível, mas pode divergir). Code-first: tipos em código geram o SDL (uma fonte, tipos sempre em sincronia, preso à lib).

Erros parciais e o campo `errors` da resposta GraphQL

GraphQL retorna `data` parcial + `errors` (com `path`) em 200 — o cliente checa `errors`, não só o status, e trata por campo. Erros de negócio: pôr num union type de retorno ('errors as data') dá contrato explícito.

Um schema, vários times: schema stitching e federação

Federação: cada serviço define/estende sua parte do schema (subgraph); um gateway compõe tudo e, em runtime, quebra a query em subconsultas e junta. Times independentes, ownership claro; custo de latência e composição.