CS Fundamentals Trainer · Guias

Projetando uma API REST

Recursos e URLs, métodos e suas garantias, códigos de status e erros, e três riscos testados: um POST repetido que cria dois pedidos, paginação com OFFSET que repete itens e requisições condicionais com ETags.

31 min de leitura

Uma API é um contrato entre programas escritos por pessoas diferentes, muitas vezes com anos de distância. Uma boa API é previsível: quem usou três dos seus endpoints consegue adivinhar o quarto, repetir requisições é seguro, os erros dizem o que fazer e as mudanças do ano que vem não quebram os clientes do ano passado. Este guia cobre as decisões de projeto que mais importam para uma API HTTP no estilo REST e testa as arriscadas: o POST repetido que cria dois pedidos, a paginação com OFFSET que repete itens e as requisições condicionais que economizam banda e impedem atualizações perdidas.

Os experimentos foram executados para este guia contra pequenos servidores locais (biblioteca padrão do Python 3.13 e SQLite), e as verificações de banco de dados das seções 6 e 7 no PostgreSQL 16. Cada um é uma única execução em uma máquina pequena. Os tamanhos e tempos absolutos dependem dos seus dados; o que vale levar são os comportamentos.

1. O que "REST" significa na prática

REST (Representational State Transfer) é um estilo descrito por Roy Fielding em sua tese de doutorado de 2000. No uso cotidiano, uma "API REST" significa:

Muitas APIs chamadas de REST são na verdade recursos mais verbos HTTP sem links de hipermídia (o nível 2 do modelo de maturidade de Richardson), e esse é um ótimo lugar para parar. O que importa é ser consistente.

2. Recursos e URLs

3. Métodos e suas garantias

Duas propriedades da especificação HTTP decidem como um cliente pode usar um método:

MétodoUsoSeguroIdempotenteSucesso típico
GETler um recurso ou uma listasimsim200
HEADcomo GET, só cabeçalhossimsim200
POSTcriar um recurso ou iniciar uma açãonãonão201 + Location, ou 202
PUTsubstituir um recurso por completonãosim200 ou 204
PATCHalterar parte de um recursonãonão garantido200 ou 204
DELETEremover um recursonãosim204 (ou 200)

Notas que enganam as pessoas:

4. Códigos de status: diga o que aconteceu

Escolha o código mais específico que serve; os clientes se ramificam pelo código antes de ler o corpo.

CódigoSignificadoUse quando
200 OKsucesso com um corpouma leitura ou uma atualização que devolve o recurso
201 Createdrecurso novodepois de um POST; acrescente um cabeçalho Location com a URL dele
202 Acceptedtrabalho enfileirado, não concluídooperações lentas (seção 11)
204 No Contentsucesso, nada a devolverDELETE, ou uma atualização que não devolve nada
301 / 308movido permanentementeum recurso tem uma URL nova
304 Not Modifiedsua cópia em cache ainda é boaGET condicional (seção 9)
400 Bad Requesta requisição está malformadaJSON ruim, um campo ausente, um tipo errado
401 Unauthorizednão autenticadocredenciais ausentes ou inválidas; envie WWW-Authenticate
403 Forbiddenautenticado, não permitidoo usuário não pode fazer isso
404 Not Foundesse recurso não existetambém usado para esconder que um recurso privado existe
405 Method Not Allowedo método não é suportado aquienvie um cabeçalho Allow
409 Conflictcolide com o estado atualvalor único duplicado, requisição já em andamento; o cliente em geral precisa atualizar a sua visão do estado (seção 6)
410 Goneexistiu, foi removido de propósitorecursos aposentados
412 Precondition Faileduma condição If-Match falhoualguém mudou antes (seção 9)
415 Unsupported Media Typenão consegue ler este Content-Typeesperava JSON, veio XML
422 Unprocessable Contentbem formada mas inválidaerros de validação de regras de negócio
429 Too Many Requestslimite de taxa atingidoenvie Retry-After (veja o guia do rate limiter)
500 / 502 / 503 / 504servidor, gateway, sobrecarga, timeout503 com Retry-After durante sobrecarga ou manutenção

Duas regras importam mais que qualquer código isolado:

  1. Nunca devolva 200 com um erro dentro. O monitoramento, os caches, as repetições e as bibliotecas de cliente confiam todos na linha de status.
  2. 4xx significa que a requisição precisa mudar, 5xx significa que o servidor falhou ao concluir uma requisição válida. É um bom ponto de partida para ler uma resposta, mas não é uma política de repetição: alguns códigos 4xx valem a repetição e nenhum 5xx diz se uma escrita aconteceu. A tabela de decisão da seção 6 é o que uma biblioteca de cliente deve implementar.

5. Erros que os clientes conseguem usar

Dê a todo erro o mesmo formato, para que os clientes escrevam um único tratador. O padrão é o Problem Details (RFC 9457, tipo de mídia application/problem+json):

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation",
  "title": "Your request has invalid fields",
  "status": 422,
  "detail": "total must be greater than zero",
  "instance": "/orders/req-7f3a",
  "errors": [{ "field": "total", "message": "must be greater than zero" }]
}

6. Repetições e chaves de idempotência

Um cliente envia POST /orders. O servidor cria o pedido, mas a resposta demora ou se perde, e o cliente dá timeout. O cliente não tem como saber se o pedido existe. Se repetir, pode criar um segundo.

Isto foi testado: um servidor que leva 0,6 s para criar um pedido, e um cliente que desiste depois de 0,3 s e tenta de novo.

Comportamento do servidorO que o cliente viuPedidos criados
Sem chave de idempotênciatimeout, depois 2012
Chave registrada depois do trabalhotimeout, depois 2012
Chave reivindicada antes do trabalho, repetição imediatatimeout, depois 4091
Chave reivindicada antes do trabalho, repetição 0,5 s depoistimeout, depois 201 (a resposta guardada)1

A correção é uma chave de idempotência: o cliente gera um valor único (um UUID) para cada operação lógica e o envia em um cabeçalho Idempotency-Key em toda tentativa. O servidor lembra da chave junto com o resultado, e uma repetição devolve o resultado guardado em vez de refazer o trabalho.

A segunda linha é a lição. Se o servidor só guarda a chave quando terminou, a repetição chega enquanto a primeira requisição ainda está rodando, não encontra nada e faz o trabalho duas vezes. A chave precisa ser reivindicada de forma atômica antes de o trabalho começar, e a reivindicação é trabalho do banco de dados, não um if no código da aplicação. (O servidor de teste respondeu 409 enquanto a primeira requisição rodava. A próxima parte mostra um projeto em que a duplicata espera e recebe a resposta guardada.)

O que uma implementação completa precisa

Uma tabela e um INSERT ... ON CONFLICT DO NOTHING são só o começo. O resto trata de onde fica a fronteira da transação, do que uma segunda requisição vê e do que sobra quando o servidor morre.

CREATE TABLE idempotency_keys (
  user_id      bigint NOT NULL,    -- keys belong to one caller, never to everybody
  key          text   NOT NULL,
  request_hash text   NOT NULL,    -- detects the same key used for a different request
  locked_until timestamptz,        -- lease for an in-progress claim (design B below)
  status       int,                -- null while the first request has not finished
  response     jsonb,
  created_at   timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (user_id, key)
);

Projeto A: tudo está no seu próprio banco de dados. A reivindicação, o trabalho e a resposta guardada compartilham uma transação:

BEGIN;                                          -- READ COMMITTED, the default
INSERT INTO idempotency_keys (user_id, key, request_hash) VALUES ($1, $2, $3)
ON CONFLICT (user_id, key) DO NOTHING;          -- 1 row: you own the key; 0 rows: someone else does
INSERT INTO orders (...) VALUES (...);          -- the business work
UPDATE idempotency_keys SET status = 201, response = $4 WHERE user_id = $1 AND key = $2;
COMMIT;

Quando zero linhas foram inseridas, faça SELECT da linha guardada: compare o seu request_hash (uma divergência é 422) e reproduza o seu status e response. O que acontece nos casos que importam, conferido no PostgreSQL 16:

SituaçãoO que a segunda requisição experimentouPedidos criados
Uma duplicata chega enquanto a primeira transação ainda está rodandoo seu INSERT esperou até a primeira confirmar (cerca de um segundo aqui), inseriu 0 linhas e então leu a resposta guardada1
A primeira transação morre antes de confirmar (uma queda simulada com ROLLBACK)o seu INSERT teve sucesso e ela mesma fez o trabalho, porque a reivindicação sumiu com o rollback1
A primeira transação confirmou, mas a resposta nunca chegou ao clientea repetição acha a resposta guardada e a devolve1
Duplicata sob REPEATABLE READo INSERT falhou com could not serialize access due to concurrent update (SQLSTATE 40001)1

Quatro consequências:

Projeto B: o trabalho sai do seu banco de dados. Suponha que a operação cobre de um provedor de pagamento. Nenhuma transação local consegue fazer a cobrança do provedor e o seu pedido serem confirmados juntos, então alguns pontos de falha deixarão um feito e o outro não. O padrão é tornar cada passo repetível:

  1. Reivindique em sua própria transação curta, confirmada na hora, com uma concessão (lease): INSERT ... (user_id, key, request_hash, locked_until) VALUES (..., now() + interval '30 seconds') ON CONFLICT DO NOTHING. Enquanto o status for nulo e a concessão for válida, uma duplicata recebe 409 com Retry-After.
  2. Recupere as reivindicações abandonadas. Se o servidor morre, a linha fica "em andamento" para sempre, a menos que algo a assuma. Uma repetição só pode assumir a reivindicação depois que a concessão expirou, e exatamente uma repetição vence:
   UPDATE idempotency_keys SET locked_until = now() + interval '30 seconds'
   WHERE user_id = $1 AND key = $2 AND status IS NULL AND locked_until < now()
   RETURNING key;                                -- 1 row: you took over; 0 rows: wait

Em um teste com uma concessão de um segundo, a primeira requisição reivindicou, uma repetição imediata recebeu zero linhas tanto na reivindicação quanto na tomada, e uma repetição depois que a concessão expirou assumiu exatamente uma vez. Escolha uma concessão mais longa que a requisição normal mais lenta; caso contrário, uma requisição lenta mas saudável é assumida enquanto ainda está rodando.

  1. Dê ao sistema externo a sua própria chave de idempotência, derivada da sua (por exemplo order-<key>). Quem assume não tem como saber se a primeira tentativa chegou ao provedor antes de morrer; passar a mesma chave ao provedor faz a repetição devolver a mesma cobrança em vez de uma nova. Se o provedor não oferece essa chave, você só pode procurar a cobrança pela sua própria referência antes de repetir, e resta uma janela que você deve fechar por reconciliação.
  2. Registre o progresso (charge_created, order_saved) para que quem assume retome depois do último passo concluído, e não do início, e termine guardando status e response.
  3. Faça os outros efeitos colaterais por uma outbox: insira uma linha de "enviar recibo" na mesma transação do pedido e deixe um worker entregá-la pelo menos uma vez. Os consumidores precisam tolerar uma duplicata (veja filas de mensagens e garantias de entrega).
Onde o servidor paraO que sobraO que a repetição faz
antes da reivindicaçãonadasegue normalmente
projeto A, antes do commitnada (rollback)segue normalmente
projeto B, depois da reivindicação, antes do trabalhouma linha em andamentorecebe 409 até a concessão acabar, depois assume
projeto B, depois de o provedor cobrar, antes de registraruma cobrança no provedor; uma linha em andamentoassume e repete a chamada com a mesma chave do provedor, que devolve a mesma cobrança
depois do commit, antes de o cliente sabero pedido e a resposta guardadareproduz a resposta guardada

Este é o limite honesto: dois sistemas não podem ser tornados atômicos por uma transação local. O que você consegue construir é uma execução at-least-once tornada inofensiva por passos idempotentes, que se comporta como exactly-once vista de fora.

Outras regras: rejeite a mesma chave com um corpo diferente (request_hash difere) com 422; restrinja as chaves ao chamador (o user_id acima) para que a chave de um cliente não colida com a de outro; e expire as chaves antigas depois de um dia ou mais.

Quando um cliente pode repetir?

Uma resposta 5xx não diz se uma escrita teve efeito. O servidor pode ter confirmado a transação e depois falhado ao responder, e um gateway pode devolver 502 ou 504 para uma requisição que o serviço atrás dele concluiu. Repetir um POST não idempotente diante dessa resposta pode, portanto, duplicar a operação. As regras para um cliente:

RespostaRepetir?Notas
Nenhuma resposta (timeout, conexão reiniciada)só se idempotente ou com chaveo resultado é desconhecido
408 Request Timeoutsimo servidor cansou de esperar pela requisição e não a processou
429 Too Many Requestssim, depois do Retry-Afterdesacelere, não martele
500 Internal Server Errorcom cuidado: idempotente ou com chave, poucas tentativaspode ser um bug que falha sempre
502 / 504igual a um timeouto resultado de uma escrita é desconhecido
503 Service Unavailablesim, respeitando o Retry-After, com backoff e um limiteo servidor está sobrecarregado ou em manutenção
501, outros 5xx persistentesnãorepetir não adianta
409 Conflictnão às cegasleia o estado atual, decida de novo e envie uma requisição nova; com uma chave de idempotência, um 409 de "ainda em andamento" pode ser repetido com a mesma chave
412 Precondition Failednãobusque o recurso de novo para pegar o novo ETag, mescle e envie de novo (seção 9)
400, 401, 403, 404, 405, 415, 422nãoa mesma requisição recebe a mesma resposta; o 401 pode ser repetido uma vez depois de renovar as credenciais

PUT e DELETE são idempotentes por definição e não precisam de chave. Os consumidores de mensagens enfrentam o mesmo problema e usam a mesma cura (veja filas de mensagens e garantias de entrega).

7. Paginação: não use OFFSET para feeds

Nunca devolva uma lista sem limite. Há dois projetos comuns.

Paginação por offset (?limit=5&offset=10) é simples e permite pular para a página 7, mas pede ao banco de dados que conte as linhas desde o começo e, pior, está errada quando a lista muda enquanto o cliente a lê.

Paginação por cursor (keyset) (?limit=5&after=<cursor>) diz "dê-me os itens depois deste". Continua rápida em páginas profundas e não repete nem pula itens quando linhas são inseridas antes do cursor. Não é um retrato consistente da lista inteira (veja abaixo).

Um experimento: 20 posts, os mais novos primeiro, 5 por página. O cliente lê a página 1, depois chegam 3 posts novos, e então ele lê a página 2.

Página 1Página 2Itens vistos duas vezes
OFFSET20, 19, 18, 17, 1618, 17, 16, 15, 1416, 17, 18
Keyset (id < 16)20, 19, 18, 17, 1615, 14, 13, 12, 11nenhum

Com a paginação por offset, as linhas novas empurraram as antigas uma página para baixo, então três itens apareceram duas vezes (e uma exclusão faria itens sumirem). A consulta keyset:

SELECT id, created_at, title
FROM posts
WHERE (created_at, id) < ($1, $2)      -- the last item of the previous page
ORDER BY created_at DESC, id DESC      -- a unique, stable sort key
LIMIT 20;

Pontos práticos:

O que a paginação keyset não promete

Um cursor lembra uma posição na ordem de classificação, não uma cópia congelada dos dados. Cada página é uma consulta nova, então as mudanças feitas entre as páginas ainda afetam o que o cliente vê. Em um teste no PostgreSQL 16 com 20 posts ordenados por updated_at DESC, id DESC, um cliente leu a página 1 (20 a 16) e, antes do resto, o post 3 foi atualizado (indo para o topo), o post 10 foi apagado e um post novo foi inserido com uma chave de ordenação atrás do cursor:

Lendo o restoResultado
Cada consulta por si só (READ COMMITTED)15, 14, 13, 21, 12, 11, 9, 8, ... o post 3 nunca apareceu (foi para a frente do cursor), o post 10 sumiu (apagado), e o post novo 21 apareceu (inserido atrás do cursor)
Todas as consultas em uma só transação REPEATABLE READ READ ONLY15, 14, ..., 3, 2, 1: os 20 posts como estavam quando a primeira página foi lida

Então a paginação keyset remove as duplicatas e lacunas causadas por inserções no topo, e nada além. Quando um cliente precisa de um conjunto de dados completo e consistente (uma exportação, uma reconciliação, um relatório), escolha uma destas:

8. Formatos de requisição e resposta

9. Cache e atualizações concorrentes com ETags

Um ETag é um identificador de uma versão de uma representação (em geral um hash ou um número de versão). Ele permite duas coisas úteis.

As leituras condicionais economizam banda. O cliente guarda o ETag e o envia de volta como If-None-Match. Se nada mudou, o servidor responde 304 Not Modified sem corpo. Medido com uma lista de 2.000 itens:

RequisiçãoStatusBytes do corpo
Primeiro GET /items200171.791
Repetição com If-None-Match3040

(Veja estratégias de cache para outros lugares onde guardar em cache.)

As escritas condicionais impedem atualizações perdidas. Duas pessoas abrem o mesmo registro. As duas o alteram. O segundo salvamento sobrescreveria o primeiro em silêncio, a mesma atualização perdida do guia de concorrência. O cliente envia o ETag que leu em um cabeçalho If-Match; se o recurso mudou desde então, o servidor recusa:

PUT /docs/9 HTTP/1.1
If-Match: "v1"

HTTP/1.1 412 Precondition Failed

No teste, os dois clientes leram a versão "v1"; o primeiro PUT teve sucesso (200, agora "v2") e o segundo, ainda carregando "v1", recebeu 412. Isto é controle de concorrência otimista: nenhum lock é mantido enquanto o usuário pensa, e um conflito é detectado ao salvar. Um servidor também pode exigir o cabeçalho respondendo 428 Precondition Required quando ele falta. Uma coluna de banco de dados com um número de versão ou updated_at faz o mesmo papel do ETag.

10. Versionamento e compatibilidade

A melhor estratégia de versionamento é não precisar de uma versão nova. As mudanças seguras (aditivas):

As mudanças que quebram os clientes:

Os clientes devem seguir a regra do leitor tolerante (ignorar campos desconhecidos), e o servidor deve seguir em troca a regra da robustez: nunca remover nem mudar o que uma versão publicada promete.

Quando uma mudança que quebra é inevitável, rode as duas versões lado a lado. Formas comuns de nomear a versão:

EstiloExemploNotas
No caminho/v2/orderso mais fácil de ver, guardar em cache e rotear; a escolha usual
Em um cabeçalho ou tipo de mídiaAccept: application/vnd.example.v2+jsonURLs mais limpas, mais difícil de testar em um navegador
Por dataApi-Version: 2026-10-01cada cliente fica preso ao comportamento que usou primeiro

Anuncie a aposentadoria cedo: marque os endpoints obsoletos na documentação, envie um cabeçalho Sunset (RFC 8594) com a data, registre quais clientes ainda chamam a versão antiga e entre em contato com eles antes de desligá-la.

11. Operações de longa duração

Se o trabalho leva mais de um ou dois segundos, não mantenha a conexão aberta. Aceite-o e deixe o cliente conferir:

POST /reports HTTP/1.1

HTTP/1.1 202 Accepted
Location: /reports/jobs/31

GET /reports/jobs/31
{ "status": "running", "progress": 40 }

GET /reports/jobs/31
HTTP/1.1 303 See Other
Location: /reports/18

O cliente consulta o recurso de status (com uma dica Retry-After para manter a consulta educada) ou recebe um webhook quando o job termina. Combinado com uma chave de idempotência, um POST repetido devolve o mesmo job em vez de iniciar um segundo. Por trás, o job costuma ficar em uma fila.

12. Segurança e limites no contrato

13. Descrevendo a API

Escreva o contrato em uma forma legível por máquina, como um documento OpenAPI. Dele você obtém páginas de referência, servidores simulados, bibliotecas de cliente geradas, validação de requisições e uma forma de detectar mudanças que quebram automaticamente em um pull request. Combine-o com exemplos dos fluxos comuns (criar, listar com um cursor, tratar um erro, repetir com uma chave de idempotência), porque os desenvolvedores leem os exemplos antes das páginas de referência. Testes de contrato que executam o servidor real contra a especificação impedem que os dois se afastem.

14. Erros comuns, e trocas que não são erros

Erros (estes quebram clientes ou perdem dados):

  1. Um grande POST /api que recebe o nome de uma ação, ou uma mistura aleatória de estilos em uma mesma API.
  2. Devolver 200 com {"success": false}.
  3. Um POST repetido que não é protegido por uma chave de idempotência, uma chave guardada só depois de o trabalho estar feito, ou uma reivindicação que nunca é recuperada depois de uma queda.
  4. Repetir uma escrita diante de um 5xx como se isso provasse que a escrita falhou.
  5. Paginação por offset em uma lista que muda, e nenhum limite para o limit.
  6. Formatos de erro diferentes em endpoints diferentes.
  7. Dinheiro em ponto flutuante, horas locais sem fuso, ids adivinháveis.
  8. Falta de autorização em nível de objeto (qualquer pessoa logada pode ler /orders/<qualquer id>).
  9. Mudanças que quebram dentro de uma versão existente.
  10. Salvar sem If-Match, de modo que edições concorrentes se sobrescrevem em silêncio.

Trocas (convenções com boas razões, não regras do REST; decida, documente e seja consistente):

15. Coisas a mencionar em uma entrevista

Perguntas que os entrevistadores gostam de acrescentar:

Resumo rápido

  1. Modele os recursos com substantivos nomeados de forma consistente (o plural é a convenção usual); o método é o verbo e o código de status é o resultado.
  2. Seguro e idempotente decidem o que pode ser repetido; o POST não é nenhum dos dois.
  3. Nunca devolva 200 para um erro; use um único formato de erro (RFC 9457) em todo lugar.
  4. Um POST repetido criou dois pedidos no teste; uma chave de idempotência reivindicada antes do trabalho criou um, e uma chave guardada só depois ainda criou dois. Um projeto completo também define a fronteira da transação, recupera reivindicações abandonadas com uma concessão e dá aos serviços externos a sua própria chave. Um 5xx nunca diz se uma escrita aconteceu.
  5. A paginação por offset repetiu três itens quando chegaram posts entre as páginas; a paginação keyset não repetiu nenhum, mas não é um snapshot: atualizações da chave de ordenação e exclusões ainda mudam o que um cliente vê, então uma exportação consistente precisa de uma ordem imutável, um snapshot ou um job de exportação.
  6. O ETag com If-None-Match transformou uma resposta de 171.791 bytes em um 304 sem corpo, e o If-Match transformou uma atualização perdida em um 412.
  7. Adicione, nunca mude nem remova; só crie versões quando precisar e aposente as versões antigas com aviso.
  8. Jobs longos devolvem 202 e um recurso de status; escreva o contrato em OpenAPI.

Fontes

  1. R. Fielding et al., RFC 9110: HTTP Semantics. Métodos, seguro e idempotente, códigos de status, requisições condicionais e entity tags.
  2. M. Nottingham, E. Wilde, S. Dalal, RFC 9457: Problem Details for HTTP APIs.
  3. M. Nottingham, RFC 8288: Web Linking (o cabeçalho Link) e E. Wilde, RFC 8594: The Sunset HTTP Header Field.
  4. M. Nottingham e R. Fielding, RFC 6585: Additional HTTP Status Codes (428, 429).
  5. P. Hoffman e J. Snell, RFC 7396: JSON Merge Patch, e P. Bryan e M. Nottingham, RFC 6902: JSON Patch.
  6. Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, capítulo 5 (REST), 2000.
  7. Martin Fowler, Richardson Maturity Model.
  8. Documentação da Stripe, Idempotent requests. Um projeto amplamente copiado de chaves de idempotência.
  9. Google, API Improvement Proposals, por exemplo a AIP-158 sobre paginação.
  10. OpenAPI Initiative, OpenAPI Specification.

Pratique este tema: Networking & APIs

Mais guias