Instruction file imported from CarlosCreAI/curso (.cursor/rules/patterns/api-design.mdc). Copyright stays with the author.

globs: /backend//.py, /api//.py, /services//*.ts alwaysApply: false

Reglas para Diseño de API

RESTful Conventions

URL Structure

• GET /api/v1/products - Lista de recursos
• GET /api/v1/products/{id} - Recurso individual
• POST /api/v1/products - Crear recurso
• PUT /api/v1/products/{id} - Actualizar recurso completo
• PATCH /api/v1/products/{id} - Actualización parcial
• DELETE /api/v1/products/{id} - Eliminar recurso

Response Format

# Respuesta exitosa
{
  "success": true,
  "data": {...},
  "meta": {
    "pagination": {...},
    "total": 100
  }
}

# Respuesta de error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Datos inválidos",
    "details": {...}
  }
}

Status Codes

• 200: GET, PUT, PATCH exitosos
• 201: POST exitoso
• 204: DELETE exitoso
• 400: Bad Request
• 401: No autenticado
• 403: Sin permisos
• 404: No encontrado
• 422: Error de validación
• 500: Error del servidor

FastAPI Patterns

• Usar Pydantic schemas para request/response
• Validación automática con Pydantic
• Dependency injection para servicios
• Async para operaciones I/O
• Documentación automática con tags