API REST e contratos
Como pedir e responder numa API: recursos, métodos, status, JSON, paginação, validação e o contrato que une backend, frontend e testes.
Cerca de 16 min · Revisado em
Ao final, você vai conseguir
- Escolher o método e o status HTTP certos para cada operação de uma API REST
- Fazer requisições com curl e interpretar status, cabeçalhos e corpo JSON
- Explicar idempotência e por que um POST repetido pode duplicar dados
- Implementar paginação com limite e validação com mensagens de erro consistentes
- Ler um contrato OpenAPI e diferenciar mudanças compatíveis de incompatíveis
Quando você paga um Pix, pede um lanche no iFood ou consulta o saldo no app do banco, a tela do celular não guarda nada: ela pergunta a uma API, um programa no servidor que responde a pedidos de outros programas. Quem trabalha com backend constrói essas APIs; quem faz frontend e quem testa conversa com elas todo dia. Saber pedir do jeito certo e entender cada resposta é o idioma comum entre essas três profissões.
Coisas e ações: recursos e métodos
Na web, esse balcão é uma API (Interface de Programação de Aplicações): um conjunto de endereços que um programa oferece para outros programas usarem. A forma mais comum de organizar esses endereços se chama REST.
No REST, a URL nomeia uma coisa, chamada recurso: /despesas é a coleção de despesas, /despesas/42 é a despesa número 42. A ação não fica na URL: quem diz o que fazer é o método HTTP, que você conheceu na aula sobre como a web funciona.
| Método | O que pede | Exemplo | Leva corpo? |
|---|---|---|---|
GET | Ler, sem mudar nada | GET /despesas/42 | Não |
POST | Criar algo novo na coleção | POST /despesas | Sim |
PUT | Substituir o recurso inteiro | PUT /despesas/42 | Sim, completo |
PATCH | Alterar só alguns campos | PATCH /despesas/42 | Sim, parcial |
DELETE | Apagar | DELETE /despesas/42 | Não |
Complete o método de cada rota da API de despesas.
____ /despesas → lista as despesas
____ /despesas → cria uma despesa
____ /despesas/42 → corrige o valor da despesa 42
____ /despesas/42 → apaga a despesa 42Qual destas rotas segue melhor o estilo REST para apagar a despesa 42?
POST /apagarDespesa?id=42GET /despesas/42/apagarDELETE /despesas/42
O corpo em JSON e o status certo
Os dados que vão e voltam ficam no corpo da mensagem. Quase toda API moderna usa JSON, um formato de texto com chaves e valores que qualquer linguagem entende: Python vira dicionário, JavaScript vira objeto, Java vira uma classe.
Uma despesa em JSON. Explore cada parte.
{
"id": 42,
"descricao": "Pão e café na padaria",
"valor": 18.5,
"pago": true,
"data": "2026-10-14"
}- Identificador: Quem cria o
idé o servidor, nunca o cliente. Ele é o que vai no final da URL:/despesas/42. - Texto (string): Textos sempre entre aspas duplas. Aspas simples não são JSON válido.
- Número: Sem aspas e com ponto decimal, nunca vírgula.
"18,50"entre aspas é um texto, e somar textos dá resultados estranhos. - Verdadeiro ou falso:
trueefalse, em minúsculas e sem aspas. - Data: JSON não tem tipo de data. A convenção é um texto no formato ano-mês-dia (ISO 8601), que ordena certo e não confunde dia com mês.
Junto com o corpo, toda resposta traz um status. Em APIs, ele é o primeiro lugar que o programa do outro lado olha para decidir o que fazer, então escolher o número certo faz parte do trabalho.
| Status | Quando usar |
|---|---|
200 OK | Leitura ou alteração que deu certo, com corpo na resposta |
201 Created | Um POST criou um recurso novo |
204 No Content | Deu certo e não há nada para devolver, comum em DELETE |
400 Bad Request | Os dados enviados estão errados ou incompletos |
401 e 403 | Falta identificação ou falta permissão (tema de outra aula) |
404 Not Found | O recurso pedido não existe |
409 Conflict | O pedido choca com o estado atual, como um e-mail já cadastrado |
500 Internal Server Error | O servidor quebrou: a culpa não é de quem pediu |
Que família de status a API deveria devolver em cada situação?
2xx: deu certo · 4xx: problema no pedido · 5xx: falha no servidor
- Uma despesa nova foi salva
- A despesa 7 foi apagada
- O valor veio como
"abc" - Pediram a despesa 9999, que não existe
- Tentaram cadastrar um e-mail que já existe
- O banco de dados caiu no meio da consulta
- Um erro de programação no servidor quebrou a rota
Conversando com a API pelo terminal
O curl é um programa que faz requisições HTTP pelo terminal, sem navegador. Use-o para conversar com uma API de despesas que está rodando no seu computador, na porta 8000.
API de despesas rodando em http://localhost:8000
Nesta pasta há dois arquivos: despesa.json e invalida.jsonListe as despesas com um
GETemhttp://localhost:8000/despesas.curl http://localhost:8000/despesas{"itens":[{"id":7,"descricao":"Mercado do mês","valor":412.9},{"id":8,"descricao":"Passagem de ônibus","valor":4.4}],"pagina":1,"total":2}Peça a despesa 7 e mostre também o status e os cabeçalhos com a opção
-i.curl -i http://localhost:8000/despesas/7HTTP/1.1 200 OK content-type: application/json {"id":7,"descricao":"Mercado do mês","valor":412.9,"categoria":"mercado"}Agora peça a despesa 999, que não existe, ainda com
-i.curl -i http://localhost:8000/despesas/999HTTP/1.1 404 Not Found content-type: application/json {"erro":"nao_encontrado","mensagem":"Despesa 999 não existe."}Veja o que há no arquivo
despesa.json.cat despesa.json{"descricao": "Passagem de ônibus", "valor": 4.4, "categoria": "transporte"}Crie a despesa enviando o arquivo com
curl -i --json @despesa.jsonpara/despesas. A opção--jsonjá usaPOSTe avisa que o corpo é JSON.curl -i --json @despesa.json http://localhost:8000/despesasHTTP/1.1 201 Created location: /despesas/9 content-type: application/json {"id":9,"descricao":"Passagem de ônibus","valor":4.4,"categoria":"transporte"}Faça o mesmo com
invalida.jsone leia com atenção o que a API responde.curl -i --json @invalida.json http://localhost:8000/despesasHTTP/1.1 400 Bad Request content-type: application/json {"erro":"validacao","detalhes":[{"campo":"valor","mensagem":"Deve ser um número maior que zero."},{"campo":"categoria","mensagem":"Use uma de: mercado, transporte, moradia, lazer, saude."}]}Apague a despesa 7 com o método
DELETE, mostrando o status.curl -i -X DELETE http://localhost:8000/despesas/7HTTP/1.1 204 No Content
Repetir sem estragar: idempotência
Uma operação é idempotente quando repeti-la deixa o sistema no mesmo estado que fazê-la uma vez. Isso importa porque a internet falha: o celular perde sinal, a resposta não chega e o app tenta de novo, sem saber se o primeiro pedido foi processado.
| Método | Seguro (não muda nada) | Idempotente |
|---|---|---|
GET | Sim | Sim |
PUT | Não | Sim: substituir duas vezes pelo mesmo conteúdo dá no mesmo |
DELETE | Não | Sim: depois da primeira vez, a despesa já não existe |
PATCH | Não | Depende: valor = 30 é; somar 10 ao valor não é |
POST | Não | Não: cada envio pode criar um recurso novo |
Um POST repetido, protegido por uma chave de idempotência
- App → API: POST /despesas + chave. O app gera uma chave única para esta tentativa, por exemplo no cabeçalho
Idempotency-Key: 5f1c, e envia junto com a despesa. - API → Banco: Salva despesa e chave. A API grava a despesa e anota que a chave
5f1cjá gerou a despesa 9. - API → App: 201 (perdida no caminho). O sinal do celular cai e a resposta nunca chega. O app não sabe se deu certo.
- App → API: Mesmo POST, mesma chave. O app tenta de novo, com a mesma chave. Sem ela, a API criaria uma segunda despesa igual.
- API → App: 201: despesa 9. A API reconhece a chave e devolve o mesmo resultado da primeira vez, sem gravar nada novo.
O app envia DELETE /despesas/7, a conexão cai e ele repete o pedido. O que deve acontecer?
- Nada de ruim: a despesa 7 continua apagada, e a segunda resposta pode ser
204ou404 - A API apaga a despesa 8, a próxima da lista
- A API deve responder
500, porque o pedido foi repetido
Por que um botão "Pagar" deveria ficar desabilitado logo após o primeiro toque, mesmo que a API use chave de idempotência?
Porque proteção boa tem camadas. O botão evita a maioria dos toques repetidos na tela; a chave protege contra as repetições que o botão não vê, como novas tentativas automáticas depois de uma queda de rede.
Listas longas: paginação
Em três anos, uma pessoa organizada lança milhares de despesas. Devolver todas em um único GET /despesas deixa a resposta lenta, gasta o plano de dados do celular e pode derrubar o servidor. A saída é paginar: entregar a lista em pedaços.
O cliente pede a página nos parâmetros; a resposta traz os itens e o contexto
GET /despesas?pagina=2&por_pagina=10
HTTP/1.1 200 OK
{
"itens": [ ...10 despesas... ],
"pagina": 2,
"por_pagina": 10,
"total": 23
}Implemente a paginação
A função listar recebe a página (começando em 1) e quantos itens por página. Hoje ela sempre devolve os 10 primeiros. Calcule inicio e fim a partir de pagina e por_pagina, e limite por_pagina a no máximo 50 antes do cálculo. Dica: a página 2 com 10 por página começa no índice 10.
despesas = [{'id': n, 'descricao': f'Despesa {n}'} for n in range(1, 24)] # 23 despesas
def listar(pagina=1, por_pagina=10):
inicio = 0
fim = 10
return {
'itens': despesas[inicio:fim],
'pagina': pagina,
'por_pagina': por_pagina,
'total': len(despesas),
}
resposta = listar(pagina=3, por_pagina=10)
print([d['id'] for d in resposta['itens']])- A página 2 começa na despesa 11
- A última página traz só as 3 que sobraram
- Uma página além do fim volta vazia, sem erro
- Funciona com outro tamanho de página
- Ninguém consegue pedir mais de 50 por página
Nunca confie na entrada
Seu formulário pode impedir valor negativo, mas qualquer pessoa consegue chamar a API direto com curl, como você fez agora há pouco. Validar no navegador é conforto para quem usa; validar no servidor é proteção. As duas coisas são necessárias.
Quando a validação falha, a resposta precisa dizer o que está errado e onde, num formato que se repete em todas as rotas. Assim o frontend mostra a mensagem ao lado do campo certo, e quem testa consegue conferir cada regra.
Um formato de erro consistente, usado em toda a API
{
"erro": "validacao",
"detalhes": [
{ "campo": "valor", "mensagem": "Deve ser um número maior que zero." }
]
}Escreva a validação da rota POST /despesas
A função criar_despesa recebe a requisição como um dicionário e devolve a resposta como outro dicionário, como um framework faria. Hoje ela aceita qualquer coisa. Adicione à lista erros um item {"campo": ..., "mensagem": ...} quando: a descricao não for um texto com algo além de espaços; o valor não for um número (int ou float) maior que zero; a categoria não estiver em CATEGORIAS. Com qualquer erro, a função já devolve 400 e não salva nada.
CATEGORIAS = {'mercado', 'transporte', 'moradia', 'lazer', 'saude'}
despesas = []
def criar_despesa(requisicao):
corpo = requisicao.get('corpo') or {}
descricao = corpo.get('descricao')
valor = corpo.get('valor')
categoria = corpo.get('categoria')
erros = []
# Escreva as validações aqui
if erros:
return {'status': 400, 'corpo': {'erro': 'validacao', 'detalhes': erros}}
despesa = {
'id': len(despesas) + 1,
'descricao': descricao,
'valor': valor,
'categoria': categoria,
}
despesas.append(despesa)
return {'status': 201, 'corpo': despesa}
print(criar_despesa({'corpo': {'descricao': 'Feira', 'valor': 52.3, 'categoria': 'mercado'}}))
print(criar_despesa({'corpo': {'descricao': '', 'valor': -5, 'categoria': 'viagem'}}))- Uma despesa correta é criada com 201
- Valor negativo devolve 400 apontando o campo valor
- Valor em texto, como "25", também é recusado
- Descrição só com espaços é recusada
- Categoria fora da lista é recusada
- Uma requisição sem corpo não salva nada
A pessoa preencheu um formulário longo e a API devolveu 400 com detalhes dizendo que o campo valor está errado. O que a tela deveria fazer?
- Limpar o formulário e mostrar "Algo deu errado"
- Manter o que foi digitado e mostrar a mensagem ao lado do campo valor
- Reenviar o mesmo pedido automaticamente até dar certo
O contrato: OpenAPI e versões
Rotas, campos, tipos, status e formato de erro formam o contrato da API: a promessa de como ela se comporta. Quem faz o frontend programa em cima dessa promessa, quem testa verifica se ela é cumprida, e outras empresas podem depender dela.
O jeito mais usado de escrever esse contrato é o OpenAPI: um arquivo YAML ou JSON que descreve cada rota. Muitos frameworks geram esse arquivo a partir do código (o FastAPI em Python, o springdoc em Java, bibliotecas como o fastify-swagger em Node) e mostram uma página interativa para testar as rotas.
Um trecho de contrato OpenAPI. Explore as partes.
paths:
/despesas/{id}:
get:
summary: Busca uma despesa
parameters:
- name: id
in: path
required: true
schema: { type: integer }
responses:
"200":
content:
application/json:
schema: { $ref: "#/components/schemas/Despesa" }
"404":
description: Despesa não encontrada- Rota: O caminho, com
{id}marcando a parte que muda. Cada rota lista os métodos que aceita. - Método: Aqui está o
GET. A mesma rota poderia terpatchedeletelogo abaixo. - Parâmetros: O que vem na URL e de que tipo.
idé obrigatório e é um número inteiro, então/despesas/abcdeve ser recusado. - Resposta de sucesso: Diz o formato do corpo quando dá certo. O
$refaponta para a definição de Despesa, escrita uma vez e reaproveitada. - Respostas de erro: Um bom contrato também documenta os erros. Sem isso, o frontend não sabe o que tratar e quem testa não sabe o que esperar.
Contratos mudam. Uma mudança compatível não quebra quem já usa a API, como acrescentar um campo novo na resposta. Uma mudança incompatível (em inglês, breaking change) quebra: renomear ou remover campos, mudar tipos, passar a exigir algo novo. Para essas, cria-se uma nova versão, como /v2/despesas, e a /v1 continua funcionando por um tempo combinado.
Cada mudança quebra os clientes atuais da API?
Compatível: pode publicar · Incompatível: precisa de nova versão
- Acrescentar o campo
criada_emna resposta - Criar a rota nova
GET /categorias - Aceitar um filtro opcional
?categoria= - Renomear
valorparamontante - Mudar
valorde número para texto - Tornar obrigatório o campo
datano POST
Quem testa a API percebe que GET /despesas/7 devolve valor como "412,90" (texto), mas o contrato diz que é um número. O que isso é?
- Um defeito: a API descumpre o próprio contrato
- Normal: JSON transforma números em texto
- Problema do frontend, que deveria converter
Fechamento
- Em REST, a URL nomeia o recurso e o método diz a ação:
GETlê,POSTcria,PUTePATCHalteram,DELETEapaga. - Os dados viajam em JSON, e o status resume o resultado: 2xx deu certo, 4xx o pedido precisa mudar, 5xx o servidor falhou.
GET,PUTeDELETEsão idempotentes;POSTnão é, e pode ser protegido por uma chave de idempotência.- Listas são paginadas com limite máximo, e toda entrada é validada no servidor, com erros num formato consistente.
- O contrato (por exemplo em OpenAPI) é a promessa da API; mudanças incompatíveis pedem uma nova versão.
Desenhe e teste o contrato da API de despesas
Use a stack que você está estudando: um framework como FastAPI, Express ou Spring se você está no backend ou fullstack, ou uma API de laboratório já pronta se você está na trilha de testes. O importante é ver cada resposta com seus próprios olhos.
- Escreva, num arquivo de texto ou OpenAPI, as rotas de listar, criar, buscar, alterar e apagar despesas, com os status de sucesso e de erro de cada uma
- Implemente ou suba a API e chame cada rota com
curl -i, anotando status e corpo - Provoque três erros: valor negativo, categoria inválida e um
idque não existe; confira se a resposta aponta o campo e usa o status certo - Liste com paginação e verifique a primeira página, a última e uma página além do fim
- Compare uma resposta da API com o registro correspondente no banco de dados e anote qualquer divergência de campo ou tipo