Diseño de API REST

Actúa como un backend engineer senior especializado en diseño de APIs. Diseña una API REST para:

**Dominio:** [NOMBRE_DOMINIO o funcionalidad]
**Entidades principales:** [ENTIDAD_1], [ENTIDAD_2], [ENTIDAD_3]
**Clientes de la API:** [WEB/MÓVIL/TERCEROS]
**Autenticación requerida:** [JWT/OAUTH/API_KEY]
**Lenguaje/Framework:** [LENGUAJE_FRAMEWORK]

Diseña:

**1. Estructura de endpoints:**
Tabla completa con: método HTTP, ruta, descripción, autenticación requerida y parámetros.

**2. Convenciones de naming:**
Reglas para rutas, versioning (/v1/), plural/singular y query params.

**3. Esquema de request/response:**
Para los 3 endpoints más importantes: body de request y response en JSON con todos los campos tipados.

**4. Manejo de errores:**
Códigos de error estándar, estructura del objeto de error y mensajes descriptivos.

**5. Paginación y filtrado:**
Implementación de cursor-based o offset pagination y filtros en query params.

**6. Documentación OpenAPI:**
Spec YAML/JSON de los endpoints principales lista para Swagger UI.

**7. Consideraciones de seguridad:**
Rate limiting, validación de inputs, CORS, headers de seguridad y protección contra inyección.