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.

Os cinco métodos que você mais vai usar
MétodoO que pedeExemploLeva corpo?
GETLer, sem mudar nadaGET /despesas/42Não
POSTCriar algo novo na coleçãoPOST /despesasSim
PUTSubstituir o recurso inteiroPUT /despesas/42Sim, completo
PATCHAlterar só alguns camposPATCH /despesas/42Sim, parcial
DELETEApagarDELETE /despesas/42Nã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 42

Qual destas rotas segue melhor o estilo REST para apagar a despesa 42?

  • POST /apagarDespesa?id=42
  • GET /despesas/42/apagar
  • DELETE /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: true e false, 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.

Os status mais comuns em uma API
StatusQuando usar
200 OKLeitura ou alteração que deu certo, com corpo na resposta
201 CreatedUm POST criou um recurso novo
204 No ContentDeu certo e não há nada para devolver, comum em DELETE
400 Bad RequestOs dados enviados estão errados ou incompletos
401 e 403Falta identificação ou falta permissão (tema de outra aula)
404 Not FoundO recurso pedido não existe
409 ConflictO pedido choca com o estado atual, como um e-mail já cadastrado
500 Internal Server ErrorO 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.json
  1. Liste as despesas com um GET em http://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}
  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/7
    HTTP/1.1 200 OK
    content-type: application/json
    
    {"id":7,"descricao":"Mercado do mês","valor":412.9,"categoria":"mercado"}
  3. Agora peça a despesa 999, que não existe, ainda com -i.

    curl -i http://localhost:8000/despesas/999
    HTTP/1.1 404 Not Found
    content-type: application/json
    
    {"erro":"nao_encontrado","mensagem":"Despesa 999 não existe."}
  4. Veja o que há no arquivo despesa.json.

    cat despesa.json
    {"descricao": "Passagem de ônibus", "valor": 4.4, "categoria": "transporte"}
  5. Crie a despesa enviando o arquivo com curl -i --json @despesa.json para /despesas. A opção --json já usa POST e avisa que o corpo é JSON.

    curl -i --json @despesa.json http://localhost:8000/despesas
    HTTP/1.1 201 Created
    location: /despesas/9
    content-type: application/json
    
    {"id":9,"descricao":"Passagem de ônibus","valor":4.4,"categoria":"transporte"}
  6. Faça o mesmo com invalida.json e leia com atenção o que a API responde.

    curl -i --json @invalida.json http://localhost:8000/despesas
    HTTP/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."}]}
  7. Apague a despesa 7 com o método DELETE, mostrando o status.

    curl -i -X DELETE http://localhost:8000/despesas/7
    HTTP/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.

O que o HTTP promete sobre cada método
MétodoSeguro (não muda nada)Idempotente
GETSimSim
PUTNãoSim: substituir duas vezes pelo mesmo conteúdo dá no mesmo
DELETENãoSim: depois da primeira vez, a despesa já não existe
PATCHNãoDepende: valor = 30 é; somar 10 ao valor não é
POSTNãoNão: cada envio pode criar um recurso novo

Um POST repetido, protegido por uma chave de idempotência

  1. 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.
  2. API → Banco: Salva despesa e chave. A API grava a despesa e anota que a chave 5f1c já gerou a despesa 9.
  3. API → App: 201 (perdida no caminho). O sinal do celular cai e a resposta nunca chega. O app não sabe se deu certo.
  4. App → API: Mesmo POST, mesma chave. O app tenta de novo, com a mesma chave. Sem ela, a API criaria uma segunda despesa igual.
  5. 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 204 ou 404
  • 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 ter patch e delete logo abaixo.
  • Parâmetros: O que vem na URL e de que tipo. id é obrigatório e é um número inteiro, então /despesas/abc deve ser recusado.
  • Resposta de sucesso: Diz o formato do corpo quando dá certo. O $ref aponta 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_em na resposta
  • Criar a rota nova GET /categorias
  • Aceitar um filtro opcional ?categoria=
  • Renomear valor para montante
  • Mudar valor de número para texto
  • Tornar obrigatório o campo data no 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: GET lê, POST cria, PUT e PATCH alteram, DELETE apaga.
  • Os dados viajam em JSON, e o status resume o resultado: 2xx deu certo, 4xx o pedido precisa mudar, 5xx o servidor falhou.
  • GET, PUT e DELETE são idempotentes; POST nã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.

  1. 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
  2. Implemente ou suba a API e chame cada rota com curl -i, anotando status e corpo
  3. Provoque três erros: valor negativo, categoria inválida e um id que não existe; confira se a resposta aponta o campo e usa o status certo
  4. Liste com paginação e verifique a primeira página, a última e uma página além do fim
  5. Compare uma resposta da API com o registro correspondente no banco de dados e anote qualquer divergência de campo ou tipo

Referências

Cursos relacionados