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:
- Recursos são as coisas sobre as quais a API trata (um pedido, um cliente, um pagamento). Cada um tem um endereço (uma URL).
- Representações são o que você troca (em geral JSON) ao ler ou alterar um recurso.
- O método HTTP diz o que você quer (ler, criar, substituir, apagar) e o código de status diz o que aconteceu. Você não inventa verbos próprios nem põe sucesso e falha dentro de um
200. - Cada requisição carrega tudo o que é preciso para tratá-la (servidor sem estado), de modo que qualquer servidor atrás de um balanceador de carga pode respondê-la. Sessões e caches passam a ser explícitos, não escondidos.
- As respostas dizem se podem ser guardadas em cache, e links ou ids permitem que os clientes se movam.
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
- Nomeie os recursos com substantivos e seja consistente quanto ao número. O plural é a convenção comum:
GET /orders,GET /orders/42,POST /orders. O singular também funciona; o REST não exige nenhum dos dois, e o que atrapalha os clientes é misturá-los. O verbo é o método, não faz parte do caminho (/getOrdere/createOrdersão RPC disfarçado). - Aninhe apenas para mostrar posse, e só um nível:
GET /orders/42/items. Além disso, dê à coisa interna o seu próprio endereço (/items/7) e filtre:GET /items?order=42. - Filtre, ordene e selecione com parâmetros de query:
GET /orders?status=paid&sort=-created_at&fields=id,total. - Ações que não cabem no CRUD podem ser uma mudança de estado ou um subrecurso.
PATCH /orders/42com{"status": "cancelled"}serve para uma atualização simples de campo em que qualquer valor é permitido.POST /orders/42/cancelé um bom projeto quando cancelar é uma operação de domínio com regras próprias, efeitos colaterais (um reembolso, uma notificação) e permissões, porque nomeia o que aconteceu e dá a essa regra um só lugar para viver. Escolha pelo que a operação significa e mantenha um único estilo dentro de um domínio. - Os ids são strings opacas e estáveis. Não exponha ids sequenciais do banco de dados se adivinhar o próximo for um problema (veja identificadores persistentes para entender por que um nome deve sobreviver à sua localização).
- Mantenha as URLs em minúsculas com hifens, sem extensões de arquivo e sem diferenças de barra final.
3. Métodos e suas garantias
Duas propriedades da especificação HTTP decidem como um cliente pode usar um método:
- Um método é seguro se não altera nada no servidor. Clientes, crawlers e caches podem chamar métodos seguros livremente.
- Um método é idempotente se chamá-lo várias vezes tem o mesmo efeito que chamá-lo uma vez. É isso que torna aceitável repetir a requisição depois de um timeout.
| Método | Uso | Seguro | Idempotente | Sucesso típico |
|---|---|---|---|---|
GET | ler um recurso ou uma lista | sim | sim | 200 |
HEAD | como GET, só cabeçalhos | sim | sim | 200 |
POST | criar um recurso ou iniciar uma ação | não | não | 201 + Location, ou 202 |
PUT | substituir um recurso por completo | não | sim | 200 ou 204 |
PATCH | alterar parte de um recurso | não | não garantido | 200 ou 204 |
DELETE | remover um recurso | não | sim | 204 (ou 200) |
Notas que enganam as pessoas:
- Idempotente não significa "mesma resposta". O segundo
DELETE /orders/42pode devolver404; o estado do servidor é o mesmo. - O
GETnunca deve alterar dados. Um link de "apagar" que seja umGETserá acionado por prefetchers e crawlers. - O
PATCHsó é idempotente se você o projetar assim: "definir o status como cancelled" é, "somar 5 ao saldo" não é. Existem formatos para descrever a mudança: JSON Merge Patch (RFC 7396) e JSON Patch (RFC 6902). - O
POSTé o perigoso, porque não é seguro nem idempotente. A seção 6 mostra o que dá errado e como corrigir.
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ódigo | Significado | Use quando |
|---|---|---|
200 OK | sucesso com um corpo | uma leitura ou uma atualização que devolve o recurso |
201 Created | recurso novo | depois de um POST; acrescente um cabeçalho Location com a URL dele |
202 Accepted | trabalho enfileirado, não concluído | operações lentas (seção 11) |
204 No Content | sucesso, nada a devolver | DELETE, ou uma atualização que não devolve nada |
301 / 308 | movido permanentemente | um recurso tem uma URL nova |
304 Not Modified | sua cópia em cache ainda é boa | GET condicional (seção 9) |
400 Bad Request | a requisição está malformada | JSON ruim, um campo ausente, um tipo errado |
401 Unauthorized | não autenticado | credenciais ausentes ou inválidas; envie WWW-Authenticate |
403 Forbidden | autenticado, não permitido | o usuário não pode fazer isso |
404 Not Found | esse recurso não existe | também usado para esconder que um recurso privado existe |
405 Method Not Allowed | o método não é suportado aqui | envie um cabeçalho Allow |
409 Conflict | colide com o estado atual | valor único duplicado, requisição já em andamento; o cliente em geral precisa atualizar a sua visão do estado (seção 6) |
410 Gone | existiu, foi removido de propósito | recursos aposentados |
412 Precondition Failed | uma condição If-Match falhou | alguém mudou antes (seção 9) |
415 Unsupported Media Type | não consegue ler este Content-Type | esperava JSON, veio XML |
422 Unprocessable Content | bem formada mas inválida | erros de validação de regras de negócio |
429 Too Many Requests | limite de taxa atingido | envie Retry-After (veja o guia do rate limiter) |
500 / 502 / 503 / 504 | servidor, gateway, sobrecarga, timeout | 503 com Retry-After durante sobrecarga ou manutenção |
Duas regras importam mais que qualquer código isolado:
- Nunca devolva
200com um erro dentro. O monitoramento, os caches, as repetições e as bibliotecas de cliente confiam todos na linha de status. 4xxsignifica que a requisição precisa mudar,5xxsignifica 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ódigos4xxvalem a repetição e nenhum5xxdiz 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" }]
}
- Um
type(ou código) estável e legível por máquina permite que os clientes se ramifiquem sem fazer parse de inglês. - Um
detailhumano ajuda o desenvolvedor que lê o log. - Inclua um id de requisição (aqui
instance, ou um cabeçalho) para que um usuário possa citá-lo e você ache a linha do log. - Nunca vaze detalhes internos: nada de stack traces, SQL ou caminhos de arquivo.
- Devolva
401/403do mesmo jeito em todo endpoint, e evite dizer a um atacante se uma conta existe (veja o guia de autenticação).
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 servidor | O que o cliente viu | Pedidos criados |
|---|---|---|
| Sem chave de idempotência | timeout, depois 201 | 2 |
| Chave registrada depois do trabalho | timeout, depois 201 | 2 |
| Chave reivindicada antes do trabalho, repetição imediata | timeout, depois 409 | 1 |
| Chave reivindicada antes do trabalho, repetição 0,5 s depois | timeout, 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ção | O que a segunda requisição experimentou | Pedidos criados |
|---|---|---|
| Uma duplicata chega enquanto a primeira transação ainda está rodando | o seu INSERT esperou até a primeira confirmar (cerca de um segundo aqui), inseriu 0 linhas e então leu a resposta guardada | 1 |
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 rollback | 1 |
| A primeira transação confirmou, mas a resposta nunca chegou ao cliente | a repetição acha a resposta guardada e a devolve | 1 |
Duplicata sob REPEATABLE READ | o INSERT falhou com could not serialize access due to concurrent update (SQLSTATE 40001) | 1 |
Quatro consequências:
- Como a reivindicação e o trabalho são confirmados juntos, não existe estado pela metade para ninguém encontrar, então nada precisa ser recuperado. Uma queda não deixa nada para trás, e um pedido confirmado sempre tem a sua resposta guardada.
- Use o
READ COMMITTEDpadrão para esta transação. SobREPEATABLE READouSERIALIZABLE, a duplicata falha com40001em vez de esperar, o que também é seguro, mas o código precisa capturar esse erro e repetir a requisição inteira. - Uma duplicata que espera segura uma conexão de banco de dados. Defina um
lock_timeout(alguns segundos) e, se ele expirar, responda409 ConflictcomRetry-After, para que uma requisição lenta não possa prender o pool. - Mantenha a transação dentro do seu próprio banco de dados. Chamar um provedor de pagamento, enviar um e-mail ou publicar uma mensagem dentro dela não faz essas ações fazerem parte da transação: se a transação der rollback, a cobrança continua lá.
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:
- 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 ostatusfor nulo e a concessão for válida, uma duplicata recebe409comRetry-After. - 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.
- 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. - 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 guardandostatuseresponse. - 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 para | O que sobra | O que a repetição faz |
|---|---|---|
| antes da reivindicação | nada | segue normalmente |
| projeto A, antes do commit | nada (rollback) | segue normalmente |
| projeto B, depois da reivindicação, antes do trabalho | uma linha em andamento | recebe 409 até a concessão acabar, depois assume |
| projeto B, depois de o provedor cobrar, antes de registrar | uma cobrança no provedor; uma linha em andamento | assume e repete a chamada com a mesma chave do provedor, que devolve a mesma cobrança |
| depois do commit, antes de o cliente saber | o pedido e a resposta guardada | reproduz 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:
- Repita conforme o método e as garantias da operação: livremente para métodos seguros (
GET,HEAD), paraPUTeDELETE(idempotentes por definição) e, para umPOST, somente com uma chave de idempotência. - Use backoff exponencial limitado com jitter: espere um tempo aleatório de até
min(cap, base * 2^attempt), pare depois de um número máximo de tentativas ou de um prazo total, e respeite oRetry-After. Sem jitter, todos os clientes repetem no mesmo instante e um servidor sobrecarregado nunca se recupera. - Repita em uma única camada. Se o cliente, um gateway e um serviço repetem três vezes cada, uma falha vira até 27 tentativas.
| Resposta | Repetir? | Notas |
|---|---|---|
| Nenhuma resposta (timeout, conexão reiniciada) | só se idempotente ou com chave | o resultado é desconhecido |
408 Request Timeout | sim | o servidor cansou de esperar pela requisição e não a processou |
429 Too Many Requests | sim, depois do Retry-After | desacelere, não martele |
500 Internal Server Error | com cuidado: idempotente ou com chave, poucas tentativas | pode ser um bug que falha sempre |
502 / 504 | igual a um timeout | o resultado de uma escrita é desconhecido |
503 Service Unavailable | sim, respeitando o Retry-After, com backoff e um limite | o servidor está sobrecarregado ou em manutenção |
501, outros 5xx persistentes | não | repetir não adianta |
409 Conflict | não às cegas | leia 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 Failed | não | busque o recurso de novo para pegar o novo ETag, mescle e envie de novo (seção 9) |
400, 401, 403, 404, 405, 415, 422 | não | a 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 1 | Página 2 | Itens vistos duas vezes | |
|---|---|---|---|
| OFFSET | 20, 19, 18, 17, 16 | 18, 17, 16, 15, 14 | 16, 17, 18 |
Keyset (id < 16) | 20, 19, 18, 17, 16 | 15, 14, 13, 12, 11 | nenhum |
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:
- A chave de ordenação precisa ser única (acrescente o id como desempate) e ter um índice que corresponda a ela.
- Faça o cursor ser uma string opaca (por exemplo, base64 dos dois valores). Assim você pode mudar o seu conteúdo depois, e os clientes não montam os próprios.
- Devolva o próximo cursor no corpo (
"next": "eyJ...") ou em um cabeçalhoLink(RFC 8288,rel="next"). Não devolva nada quando não há mais itens. - Limite o
limit(por exemplo 100) e dê a ele um padrão. - O offset serve para listas pequenas e que raramente mudam e para tabelas administrativas. Para feeds e linhas do tempo use um cursor; para exportações, leia "O que a paginação keyset não promete" abaixo. O guia do news feed mede a diferença de velocidade no PostgreSQL.
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 resto | Resultado |
|---|---|
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 ONLY | 15, 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:
- Uma ordenação que as atualizações não possam mudar. Ordene por uma chave imutável (
idoucreated_at) em vez deupdated_at, para que editar uma linha não possa movê-la para o outro lado do cursor. As exclusões ainda podem remover itens, então use marcadores de exclusão lógica se os clientes precisarem vê-las. - Um limite de snapshot. Ponha um limite superior no cursor (
created_at <= T, tomado quando a primeira página foi servida) para que as linhas que chegam depois sejam excluídas. - Um snapshot de verdade do banco de dados. Ler todas as páginas em uma transação
REPEATABLE READ(ou a partir de um snapshot exportado) dá o resultado acima, mas mantém uma transação aberta, o que atrasa a limpeza de versões antigas de linhas, então serve a um job limitado e não a um cliente que pode levar uma hora entre as páginas. - Um job de exportação dedicado:
POST /exportsdevolve202e um recurso de status (seção 11); o servidor monta o arquivo a partir de um snapshot, e o cliente o baixa quando estiver pronto.
8. Formatos de requisição e resposta
- Um único estilo de nomes para os campos JSON (
snake_caseoucamelCase), em todo lugar. - Datas e horas como strings ISO 8601 em UTC (
2026-10-23T14:30:00Z); dinheiro como um inteiro na menor unidade mais um código de moeda ({"amount": 1999, "currency": "USD"}), nunca um número de ponto flutuante. - Devolva o recurso criado ou atualizado de
POSTePATCH, para que os clientes não precisem de uma segunda requisição. - Prefira listas dentro de um objeto:
{"items": [...], "next": "..."}. Um array puro não pode ganhar depois um camponextou um total sem quebrar os clientes. Isto é uma troca, não uma regra: um array no topo é perfeitamente válido para uma lista pequena e fixa, ou quando a informação de paginação viaja em cabeçalhos (Link, RFC 8288) em vez de no corpo. - Use
nullou omita um campo de forma consistente, e documente qual dos dois. - Rejeite campos desconhecidos na escrita só se for preciso. Na leitura, os clientes devem ignorar campos que não conhecem (a regra do leitor tolerante, seção 10).
- Valide no servidor o que o cliente já conferiu.
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ção | Status | Bytes do corpo |
|---|---|---|
Primeiro GET /items | 200 | 171.791 |
Repetição com If-None-Match | 304 | 0 |
(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):
- adicionar um endpoint novo, um campo opcional de requisição ou um campo novo em uma resposta
- adicionar um valor novo a uma resposta que os clientes tratam como um conjunto aberto (com a documentação dizendo isso)
As mudanças que quebram os clientes:
- remover ou renomear um campo ou endpoint
- mudar o tipo, o formato ou o significado de um campo
- tornar obrigatório um campo opcional, ou adicionar um novo campo obrigatório na requisição
- mudar os códigos de status ou o formato de erro
- endurecer a validação
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:
| Estilo | Exemplo | Notas |
|---|---|---|
| No caminho | /v2/orders | o mais fácil de ver, guardar em cache e rotear; a escolha usual |
| Em um cabeçalho ou tipo de mídia | Accept: application/vnd.example.v2+json | URLs mais limpas, mais difícil de testar em um navegador |
| Por data | Api-Version: 2026-10-01 | cada 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
- Use apenas HTTPS (veja TLS e HTTPS). Redirecionar
httpparahttpsnão basta para uma API: os clientes talvez já tenham enviado um segredo. - Autentique toda requisição e autorize todo objeto: saber que
/orders/42existe não deve deixar o usuário B ler o pedido do usuário A (a falha mais comum em APIs é a falta de uma verificação em nível de objeto). O guia de autenticação cobre sessões, tokens e OAuth. - Limite a taxa por cliente e devolva
429comRetry-Aftere, se quiser, a cota restante em cabeçalhos (veja o guia do rate limiter). - Limite os tamanhos: corpo da requisição, tamanho da página, número de ids por chamada e tempo por requisição.
- Defina o
Content-Typeem toda resposta e rejeite requisições com o errado (415). - Não ponha segredos em URLs. As URLs vão parar em logs, no histórico do navegador e em cabeçalhos
Referer.
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):
- Um grande
POST /apique recebe o nome de uma ação, ou uma mistura aleatória de estilos em uma mesma API. - Devolver
200com{"success": false}. - Um
POSTrepetido 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. - Repetir uma escrita diante de um
5xxcomo se isso provasse que a escrita falhou. - Paginação por offset em uma lista que muda, e nenhum limite para o
limit. - Formatos de erro diferentes em endpoints diferentes.
- Dinheiro em ponto flutuante, horas locais sem fuso, ids adivinháveis.
- Falta de autorização em nível de objeto (qualquer pessoa logada pode ler
/orders/<qualquer id>). - Mudanças que quebram dentro de uma versão existente.
- 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):
- Nomes de recursos no plural ou no singular.
- Verbos em caminhos de ação (
POST /orders/42/cancel) ou uma mudança de estado porPATCH. - Uma lista dentro de um objeto (espaço para crescer) ou um array puro (bom quando você nunca vai precisar de metadados, ou quando eles viajam em cabeçalhos).
- Paginação por offset para listas administrativas pequenas, onde a sua simplicidade vence.
15. Coisas a mencionar em uma entrevista
- Comece pelos recursos e pelas operações, depois escolha URLs e métodos; mencione seguro e idempotente e por que as repetições dependem disso.
- Use os códigos de status com precisão e dê as distinções entre 401 e 403 e entre 404 e 410.
- Projete para repetições: chaves de idempotência para
POST, reivindicadas de forma atômica antes do trabalho, com a reivindicação e o resultado na mesma transação quando possível. Saiba dizer o que acontece se o servidor cair em cada passo, e que um provedor de pagamento precisa da sua própria chave de idempotência. Repita pela semântica do método, com backoff limitado e jitter. - Pagine com cursores e explique o que dá errado com offsets.
- Mencione o controle de concorrência com
ETag/If-Matchou uma coluna de versão. - Mencione a compatibilidade: mudanças aditivas, leitores tolerantes, versionamento, obsolescência com uma data
Sunset. - Mencione a operação: limites de taxa, ids de requisição, timeouts, jobs de longa duração com
202e OpenAPI.
Perguntas que os entrevistadores gostam de acrescentar:
- "
PUTouPATCH?" OPUTsubstitui o recurso inteiro e é idempotente; oPATCHaltera partes e precisa ser projetado para ser idempotente. - "Um cliente diz que foi cobrado duas vezes. Como isso pode acontecer e como você evita?" Uma repetição depois de um timeout ou de um
5xxpara uma escrita que na verdade tinha sido confirmada. Uma chave de idempotência com uma reivindicação atômica, a mesma chave passada ao provedor de pagamento e uma regra de recuperação para reivindicações abandonadas por uma queda. - "Como você deixa um cliente ler todos os 10 milhões de registros?" Um cursor sobre uma chave de ordenação indexada, única e imutável, e um limite de tamanho de página. Um cursor não é um snapshot, então, se o cliente precisa de uma cópia consistente, acrescente um limite de snapshot ou use um job de exportação (
202) construído a partir de um snapshot do banco de dados. - "REST, GraphQL ou gRPC?" REST para recursos públicos simples e cache pelo HTTP; GraphQL quando os clientes precisam escolher campos entre muitos recursos; gRPC para chamadas internas de baixa latência entre serviços com um contrato tipado.
- "Como você muda o nome de um campo sem quebrar os clientes?" Adicione o campo novo, mantenha o antigo, anuncie a obsolescência e remova-o em uma versão posterior.
Resumo rápido
- 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.
- Seguro e idempotente decidem o que pode ser repetido; o
POSTnão é nenhum dos dois. - Nunca devolva
200para um erro; use um único formato de erro (RFC 9457) em todo lugar. - Um
POSTrepetido 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. Um5xxnunca diz se uma escrita aconteceu. - 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.
- O
ETagcomIf-None-Matchtransformou uma resposta de 171.791 bytes em um304sem corpo, e oIf-Matchtransformou uma atualização perdida em um412. - Adicione, nunca mude nem remova; só crie versões quando precisar e aposente as versões antigas com aviso.
- Jobs longos devolvem
202e um recurso de status; escreva o contrato em OpenAPI.
Fontes
- R. Fielding et al., RFC 9110: HTTP Semantics. Métodos, seguro e idempotente, códigos de status, requisições condicionais e entity tags.
- M. Nottingham, E. Wilde, S. Dalal, RFC 9457: Problem Details for HTTP APIs.
- M. Nottingham, RFC 8288: Web Linking (o cabeçalho
Link) e E. Wilde, RFC 8594: The Sunset HTTP Header Field. - M. Nottingham e R. Fielding, RFC 6585: Additional HTTP Status Codes (
428,429). - P. Hoffman e J. Snell, RFC 7396: JSON Merge Patch, e P. Bryan e M. Nottingham, RFC 6902: JSON Patch.
- Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, capítulo 5 (REST), 2000.
- Martin Fowler, Richardson Maturity Model.
- Documentação da Stripe, Idempotent requests. Um projeto amplamente copiado de chaves de idempotência.
- Google, API Improvement Proposals, por exemplo a AIP-158 sobre paginação.
- OpenAPI Initiative, OpenAPI Specification.
Pratique este tema: Networking & APIs