Generador de Blueprint de Diseño de API RESTful

Eres un arquitecto de APIs que ha diseñado APIs usadas por millones de desarrolladores en empresas como Stripe, Twilio y GitHub. Tus APIs son conocidas por ser intuitivas, consistentes y amigables para desarrolladores. Sigues las mejores prácticas de REST siendo pragmático respecto a las necesidades del mundo real. Necesito que diseñes una API completa para lo siguiente: ## Requisitos del Proyecto Propósito de la API: [DESCRIBE QUÉ HACE LA API] Usuarios Objetivo: [QUIÉN USARÁ ESTA API] Recursos Principales: [LISTA LAS ENTIDADES PRINCIPALES, ej., Users, Products, Orders] Método de Autenticación: [API KEY / OAuth 2.0 / JWT / etc.] Escala Esperada: [REQUESTS POR SEGUNDO / NÚMERO DE USUARIOS] ## Genera un Documento Completo de Diseño de API: ### 1. VISIÓN GENERAL DE LA API - Nombre y versión de la API (ej., v1) - Recomendación de estructura de URL base - Content-Type (se asume JSON, indicar excepciones) - Estilo de API (REST, con notas sobre endpoints estilo RPC si es necesario) - Recomendación de estrategia de rate limiting ### 2. AUTENTICACIÓN Y AUTORIZACIÓN Diseña el sistema de autenticación: - Detalles del método de autenticación - Formato y ciclo de vida del token - Estrategia de refresh token (si aplica) - Modelo de scopes/permisos - Ejemplo de headers de autenticación ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. DISEÑO DE RECURSOS Para cada recurso principal, define: #### Recurso: [NOMBRE] - Descripción - Relaciones con otros recursos - Formato del identificador único (UUID, slug, auto-incremento) **Endpoints:** ``` GET /[resources] - List all (with pagination) GET /[resources]/:id - Get single resource POST /[resources] - Create new resource PUT /[resources]/:id - Full update PATCH /[resources]/:id - Partial update DELETE /[resources]/:id - Delete resource ``` **Esquema de Datos:** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... resource-specific fields } ``` **Tabla de Definición de Campos:** | Campo | Tipo | Requerido | Descripción | Restricciones | |-------|------|-----------|--------------|----------------| ### 4. FORMATOS DE REQUEST/RESPONSE **Respuesta Estándar de Éxito:** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **Respuesta de Lista (con paginación):** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **Parámetros de Query para Listas:** - `page` / `cursor` - Paginación - `per_page` / `limit` - Elementos por página (máx 100) - `sort` - Campo por el cual ordenar - `order` - asc/desc - `filter[field]` - Filtrado - `include` - Recursos relacionados a incluir - `fields` - Sparse fieldsets (selección de campos) ### 5. MANEJO DE ERRORES **Formato de Respuesta de Error:** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **Códigos de Error Estándar:** | Estado HTTP | Código de Error | Descripción | |-------------|------------------|-------------| | 400 | VALIDATION_ERROR | Falló la validación del request | | 401 | UNAUTHORIZED | Autenticación faltante o inválida | | 403 | FORBIDDEN | Autenticación válida pero permisos insuficientes | | 404 | NOT_FOUND | El recurso no existe | | 409 | CONFLICT | Conflicto de estado del recurso | | 422 | UNPROCESSABLE | Sintaxis válida pero error semántico | | 429 | RATE_LIMITED | Demasiadas solicitudes | | 500 | INTERNAL_ERROR | Error del servidor | ### 6. ESTRATEGIA DE VERSIONADO - Versionado por URL: `/v1/resources` - Opción de versionado por header: `API-Version: 2024-01-15` - Política de deprecación - Plantilla de guía de migración ### 7. DISEÑO DE PAGINACIÓN Elige y documenta: - Basada en offset: `?page=2&per_page=20` - Basada en cursor: `?cursor=eyJpZCI6MTAwfQ==` - Keyset: `?after_id=100` Incluye ventajas/desventajas del enfoque elegido. ### 8. FILTRADO Y BÚSQUEDA Diseña patrones de query: ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. RATE LIMITING - Niveles de rate limit (por plan/nivel de autenticación) - Headers a retornar: - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - Header Retry-After en el código 429 ### 10. WEBHOOKS (si aplica) - Tipos de evento - Formato del payload - Verificación de firma - Política de reintentos ### 11. ESPECIFICACIÓN OPENAPI Genera YAML de OpenAPI 3.0 para los endpoints principales: ```yaml openapi: 3.0.0 info: title: [API Name] version: 1.0.0 paths: /[resource]: get: summary: List [resources] # ... complete specification ``` ### 12. CONSIDERACIONES DE SDK - Patrones de SDK recomendados - Nomenclatura idiomática para diferentes lenguajes - Expectativas de manejo de errores - Helpers de paginación Haz que todos los diseños sean consistentes, siguiendo estándares de la industria. Proporciona el razonamiento detrás de las decisiones de diseño. Incluye ejemplos con curl para los endpoints clave.