Conceptos básicos de diseño de API
9 ejemplos para el diseño de API HTTP: 6 básicos y 3 intermedios.
Prerrequisitos
uv pip install fastapi pydantic python-jose[cryptography] argon2-cffi httpx- Los patrones de seguridad aquí se aplican a las API de FastAPI, Django y Flask en Python 3.14.
Ejemplos básicos
1. URL de recursos
Sustantivos en las rutas, verbos en los métodos HTTP.
GET /users
POST /users
GET /users/{id}
PATCH /users/{id}
DELETE /users/{id}- Nombres de recursos en plural.
- Evitar URL de acciones estilo RPC para CRUD.
- Anidar sub-recursos: /users/{id}/orders.
Relacionado: GraphQL en Python - modelo de consulta alternativo
2. Códigos de estado
Mapear resultados a la semántica HTTP.
201 Created on POST success
204 No Content on DELETE success
409 Conflict on duplicate resource- No devolver 200 para errores.
- 422 para fallos de validación.
- 429 para límites de tasa.
3. Envoltorio de errores
Errores estables legibles por máquina.
{"error": {"code": "invalid_email", "message": "El formato del correo electrónico es inválido", "field": "email"}}- Incluir código, mensaje, campo opcional.
- Registrar el ID de correlación en el servidor.
- Nunca filtrar trazas de pila.
Relacionado: Validación de entrada e inyección - errores de validación
4. Versionado
Versiones explícitas de la API.
/v1/users
Accept: application/vnd.example.v1+json- El prefijo de URL es lo más sencillo.
- Documentar plazos de deprecación.
- Evitar cambios disruptivos silenciosos.
5. Paginación
Patrones de cursor o desplazamiento.
?limit=20&cursor=eyJpZCI6MTB9- Preferir cursores para tablas grandes.
- Incluir el total solo cuando sea barato.
- Limitar el tamaño máximo de página.
6. Idempotencia
Reintentos seguros para POST.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000- Almacenar el mapeo de clave a resultado con TTL.
- Crítico para pagos.
- Devolver la misma respuesta en caso de repetición.
Ejemplos intermedios
7. Encabezado de autenticación
Tokens Bearer.
Authorization: Bearer <access_token>- Solo HTTPS.
- Tokens de acceso de corta duración.
- Refresco separado para navegadores.
Relacionado: OAuth2 y JWT - flujos
8. Encabezados de límite de tasa
Informar a los clientes de la cuota restante.
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
Retry-After: 60- Devolver 429 cuando se exceda.
- Documentar límites en OpenAPI.
- Límites más estrictos en rutas autenticadas.
Relacionado: Límites de tasa y prevención de abusos - aceleradores
9. Contrato OpenAPI
Publicar esquema para los clientes.
openapi: 3.1.0
paths:
/health:
get:
responses:
"200":
description: OK- Generación de código para clientes.
- Pruebas de contrato en CI.
- Mantener ejemplos realistas.
Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 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+ y uv 0.6+.