Revision de Diseno de API

El Problema

Un mal diseno de API crea deuda tecnica permanente. Una vez que los clientes se integran con tus endpoints, cambiar el contrato rompe su codigo. Nomenclatura inconsistente, paginacion faltante, respuestas de error confusas y ninguna estrategia de versionado se acumulan en una API que nadie quiere consumir y nadie puede evolucionar con seguridad.

El Prompt

Revisa el siguiente diseno de API. Actua como un arquitecto API senior evaluando consistencia, escalabilidad y experiencia del desarrollador.

TIPO DE API: [REST / GraphQL / gRPC]
CONSUMIDORES: [ej. app movil, desarrolladores terceros, frontend interno]
SPEC/CODIGO:
[pegar definiciones de rutas, spec OpenAPI o codigo del controlador]

Evalua en estas dimensiones:

1. **Diseno de Recursos**
   - Los recursos se nombran como sustantivos (no verbos)? Plural o singular consistente?
   - Los recursos anidados estan correctamente definidos (/users/:id/orders)?
   - La jerarquia es poco profunda (max 2-3 niveles)?

2. **Semantica HTTP**
   - Los metodos HTTP se usan correctamente (GET lee, POST crea, PUT reemplaza, PATCH actualiza, DELETE elimina)?
   - Los requests GET tienen efectos secundarios?
   - Los codigos de estado son precisos (201 para creacion, 204 sin contenido)?

3. **Paginacion & Filtrado**
   - Los endpoints de lista soportan paginacion (cursor-based preferido)?
   - Se incluye conteo total / indicador de siguiente pagina?
   - Se soportan filtros, ordenamiento y seleccion de campos?

4. **Respuestas de Error**
   - El formato de error es consistente en todos los endpoints?
   - Los errores incluyen: codigo de estado, tipo, mensaje humano y codigo legible por maquina?
   - Los errores de validacion se detallan por campo?

5. **Versionado**
   - Hay estrategia de versionado (ruta URL, header, query param)?

6. **Seguridad**
   - Se requiere autenticacion en todos los endpoints no publicos?
   - Los rate limits estan documentados?

Para cada problema, proporciona:
- **Endpoint**: La ruta afectada
- **Severidad**: Breaking / Inconsistente / Mejora
- **Problema**: Que viola las mejores practicas
- **Fix**: Diseno corregido con ejemplo de request/response

Ejemplo de Salida

## Revision de Diseno de API: 6 problemas encontrados

### Breaking: Formato de Error Inconsistente
Endpoints retornan diferentes formas de error:
  POST /users → { "error": "Email tomado" }
  GET /orders → { "message": "No encontrado", "code": 404 }
Fix: Estandarizar:
  { "status": 404, "error": "NOT_FOUND", "message": "Orden con ID 123 no encontrada", "details": [] }

### Breaking: Endpoint de Lista Sin Limites
GET /api/products retorna TODOS los productos sin paginacion.
Fix: Paginacion cursor-based por defecto:
  GET /api/products?limit=20&cursor=abc123

Cuando Usar

Ejecutar antes de publicar una API a consumidores externos, durante revisiones de diseno para nuevos endpoints, o al auditar una API existente. Mas valioso temprano en la fase de diseno.

Tips Pro

• Incluir todos los endpoints — los problemas de diseno de API suelen ser de consistencia a traves de la superficie completa.
• Especificar consumidores — clientes moviles necesitan diferente paginacion que dashboards web.
• Pedir spec OpenAPI — “Genera una spec OpenAPI 3.0 para el diseno de API corregido.”
• Versionar desde el dia uno — agregar /v1/ no cuesta nada ahora y ahorra enorme dolor de migracion despues.