Noções Básicas de Design de API
9 exemplos para design de API HTTP - 6 básicos e 3 intermediários.
Pré-requisitos
uv pip install fastapi pydantic python-jose[cryptography] argon2-cffi httpx- Padrões de segurança aqui se aplicam a APIs FastAPI, Django e Flask em Python 3.14.
Exemplos Básicos
1. URLs de Recursos
Substantivos em caminhos, verbos em métodos HTTP.
GET /users
POST /users
GET /users/{id}
PATCH /users/{id}
DELETE /users/{id}- Nomes de recursos no plural.
- Evite URLs de ação estilo RPC para CRUD.
- Aninhe sub-recursos: /users/{id}/orders.
Relacionado: GraphQL em Python - modelo de consulta alternativo
2. Códigos de Status
Mapeie resultados para semântica HTTP.
201 Created on POST success
204 No Content on DELETE success
409 Conflict on duplicate resource- Não retorne 200 para erros.
- 422 para falhas de validação.
- 429 para limites de taxa.
3. Envelope de Erro
Erros estáveis e legíveis por máquina.
{"error": {"code": "invalid_email", "message": "Email format invalid", "field": "email"}}- Inclua código, mensagem, campo opcional.
- Registre ID de correlação no lado do servidor.
- Nunca vaze rastros de pilha (stack traces).
Relacionado: Validação de Entrada e Injeção - erros de validação
4. Versionamento
Versões explícitas da API.
/v1/users
Accept: application/vnd.example.v1+json- Prefixo de URL é o mais simples.
- Documente cronogramas de descontinuação.
- Evite alterações que quebram sem aviso.
5. Paginação
Padrões de cursor ou offset.
?limit=20&cursor=eyJpZCI6MTB9- Prefira cursores para tabelas grandes.
- Inclua o total apenas quando for barato.
- Limite o tamanho máximo da página.
6. Idempotência
Retentativas seguras para POST.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000- Armazene o mapeamento chave para resultado com TTL.
- Crítico para pagamentos.
- Retorne a mesma resposta em caso de repetição.
Exemplos Intermediários
7. Cabeçalho de Autenticação
Tokens Bearer.
Authorization: Bearer <access_token>- Apenas HTTPS.
- Tokens de acesso de curta duração.
- Refrescamento separado para navegadores.
Relacionado: OAuth2 & JWT - fluxos
8. Cabeçalhos de Limite de Taxa
Informe aos clientes a cota restante.
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
Retry-After: 60- Retorne 429 quando excedido.
- Documente limites no OpenAPI.
- Limites mais rigorosos em rotas autenticadas.
Relacionado: Limitação de Taxa e Prevenção de Abuso - throttles
9. Contrato OpenAPI
Publique o esquema para os clientes.
openapi: 3.1.0
paths:
/health:
get:
responses:
"200":
description: OK- Geração de código para clientes.
- Testes de contrato em CI.
- Mantenha exemplos realistas.
Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.