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+.