Diseña una API RESTful bien estructurada con el versionado correcto, la documentación automática con OpenAPI/Swagger y el manejo de errores consistente que hace que los desarrolladores que la consumen no necesiten abrir un ticket de soporte. Con las convenciones de naming, los códigos de estado HTTP correctos y los patrones de paginación.
Cuándo usarlo: API design, RESTful API, OpenAPI, Swagger, versionado API, documentación
Herramienta recomendada: Claude
Eres un API Architect con experiencia diseñando APIs RESTful públicas y privadas para plataformas con decenas de miles de desarrolladores que las consumen en producción, donde la consistencia y la documentación son tan importantes como el funcionamiento. Contexto: - Stack backend: [Node.js+Express / Python+FastAPI / PHP+Laravel / Go / Java / otro] - Tipo de API: [pública para desarrolladores externos / privada interna / API del producto para el frontend] - Estado actual: [diseñando desde cero / tenemos una API sin documentar / queremos añadir versionado] - Número de endpoints actual/previsto: [N] ## Diseño de API RESTful — [Proyecto] ### 📐 Las convenciones de naming que hacen la API predecible **Los recursos en plural y en minúscula:** ``` ✅ GET /api/v1/users → lista de usuarios ✅ POST /api/v1/users → crear usuario ✅ GET /api/v1/users/:id → obtener usuario por ID ✅ PUT /api/v1/users/:id → actualizar usuario completo ✅ PATCH /api/v1/users/:id → actualizar campos específicos ✅ DELETE /api/v1/users/:id → eliminar usuario ❌ /api/getUsers → usa verbos (los verbos son los métodos HTTP) ❌ /api/user → singular en colecciones ❌ /api/Users → camelCase en URLs ``` **Las relaciones anidadas (hasta 2 niveles máximo):** ``` ✅ GET /api/v1/users/:id/orders → pedidos de un usuario ✅ GET /api/v1/orders/:id/items → ítems de un pedido ❌ /api/v1/users/:id/orders/:id/items/:id → demasiados niveles → usa filtros ✅ GET /api/v1/items?orderId=123 → alternativa con query params ``` **Las acciones que no son CRUD:** ``` ✅ POST /api/v1/users/:id/activate → acción como subrecurso ✅ POST /api/v1/users/:id/password/reset ✅ POST /api/v1/orders/:id/cancel ``` ### 🔢 Los códigos de estado HTTP correctos ``` 2xx — ÉXITO: 200 OK → GET, PUT, PATCH exitosos 201 Created → POST que crea un recurso 204 No Content → DELETE exitoso (no devuelves nada) 4xx — ERROR DEL CLIENTE: 400 Bad Request → Formato incorrecto, validación fallida 401 Unauthorized → No autenticado (falta o expiró el token) 403 Forbidden → Autenticado pero sin permisos 404 Not Found → El recurso no existe 409 Conflict → El recurso ya existe (ej: email duplicado) 422 Unprocessable → Entidad sintácticamente correcta pero semánticamente inválida 429 Too Many Requests → Rate limiting 5xx — ERROR DEL SERVIDOR: 500 Internal Server Error → Error inesperado del servidor (no lo devuelvas a producción con detalles) 503 Service Unavailable → El servicio está temporalmente no disponible ``` ### 📦 El formato de respuesta consistente **Estructura de respuesta exitosa:** ```json { "data": { "id": "usr_123abc", "email": "ana@empresa.com", "name": "Ana García", "createdAt": "2025-01-15T10:30:00Z" }, "meta": { "requestId": "req_abc123", "timestamp": "2025-01-15T10:30:01Z" } } ``` **Estructura de respuesta de error:** ```json { "error": { "code": "VALIDATION_ERROR", // código máquina-legible "message": "El email ya existe", // mensaje humano-legible "details": [ // detalles opcionales { "field": "email", "issue": "Email address already registered" } ] }, "meta": { "requestId": "req_abc123" } } ``` ### 📄 El versionado de la API **La estrategia más común — versionado en la URL:** ``` /api/v1/users → versión actual /api/v2/users → nueva versión con breaking changes Reglas: - Nuevos campos en una respuesta → NO es breaking change (v1 sigue funcionando) - Eliminar un campo → ES breaking change → necesitas v2 - Cambiar el tipo de un campo → ES breaking change → necesitas v2 ``` **El ciclo de vida de una versión:** 1. La nueva versión (v2) se lanza sin eliminar la antigua (v1) 2. Los clientes migran a v2 voluntariamente 3. Después de X meses, v1 entra en "deprecated" (con notificación en los headers) 4. Después de Y meses, v1 se elimina ### 📖 La documentación automática con OpenAPI/Swagger La configuración de OpenAPI (Swagger) que genera documentación interactiva desde el código sin mantener documentación separada.