7 min lectura • Guide 747 of 877
Mejores Prácticas de Desarrollo de APIs
Las APIs son contratos entre sistemas. GitScrum ayuda a los equipos a planificar, rastrear y entregar trabajo de API con documentación y testing apropiados.
Planificación de API
Historias de API en GitScrum
ESTRUCTURA DE HISTORIA DE API:
┌─────────────────────────────────────────────────────────────┐
│ API-123: Endpoint de Crear Usuario │
├─────────────────────────────────────────────────────────────┤
│ │
│ Como consumidor de API │
│ Puedo crear un nuevo usuario via POST /api/v1/users │
│ Para poder incorporar usuarios programáticamente │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ ESPECIFICACIÓN DEL ENDPOINT: │
│ │
│ Método: POST │
│ Path: /api/v1/users │
│ Auth: Bearer token requerido │
│ │
│ Request Body: │
│ { │
│ "email": "usuario@ejemplo.com", │
│ "name": "Juan Pérez", │
│ "role": "member" │
│ } │
│ │
│ Response de Éxito (201): │
│ { │
│ "id": "usr_abc123", │
│ "email": "usuario@ejemplo.com", │
│ "name": "Juan Pérez", │
│ "role": "member", │
│ "created_at": "2024-01-15T10:30:00Z" │
│ } │
│ │
│ Responses de Error: │
│ 400 - Input inválido (campo faltante, formato inválido) │
│ 401 - Autenticación requerida │
│ 403 - Permisos insuficientes │
│ 409 - Email ya existe │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ CRITERIOS DE ACEPTACIÓN: │
│ ☐ Endpoint acepta datos de usuario válidos │
│ ☐ Retorna 201 con usuario creado │
│ ☐ Valida formato de email │
│ ☐ Rechaza emails duplicados (409) │
│ ☐ Requiere autenticación │
│ ☐ Documentación actualizada │
│ ☐ Tests cubren happy path y errores │
└─────────────────────────────────────────────────────────────┘
Checklist de Diseño de API
PRINCIPIOS DE DISEÑO DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CONVENCIONES DE NOMBRADO: │
│ ────────────────────────── │
│ ✅ Recursos son sustantivos, plural: │
│ /users, /projects, /tasks │
│ │
│ ✅ Usa kebab-case para multi-palabra: │
│ /project-members, /time-entries │
│ │
│ ✅ Anida para relaciones: │
│ /projects/{id}/tasks │
│ /users/{id}/notifications │
│ │
│ ❌ No uses verbos en path: │
│ /getUsers → GET /users │
│ /createProject → POST /projects │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ MÉTODOS HTTP: │
│ ─────────────── │
│ GET - Obtener recurso(s) │
│ POST - Crear nuevo recurso │
│ PUT - Reemplazar recurso completo │
│ PATCH - Actualizar parte de recurso │
│ DELETE - Eliminar recurso │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ CÓDIGOS DE ESTADO: │
│ ─────────────────── │
│ 200 OK - GET/PUT/PATCH exitoso │
│ 201 Created - POST exitoso │
│ 204 No Content - DELETE exitoso │
│ 400 Bad Request - Input inválido │
│ 401 Unauthorized - Sin auth │
│ 403 Forbidden - Sin permiso │
│ 404 Not Found - Recurso no existe │
│ 409 Conflict - Duplicado/conflicto │
│ 422 Unprocessable - Validación falló │
│ 500 Server Error - Nuestra culpa │
└─────────────────────────────────────────────────────────────┘
Versionado de API
Estrategia de Versión
ENFOQUES DE VERSIONADO DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ VERSIONADO EN URL (Recomendado): │
│ ───────────────────────────────── │
│ /api/v1/users │
│ /api/v2/users │
│ │
│ ✅ Más explícito │
│ ✅ Fácil de cachear │
│ ✅ Obvio en logs │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ VERSIONADO SEMÁNTICO: │
│ ────────────────────── │
│ │
│ MAJOR.MINOR.PATCH (ej: 2.3.1) │
│ │
│ MAJOR: Cambio que rompe │
│ • Campos removidos │
│ • Estructura cambiada │
│ • Comportamiento diferente │
│ │
│ MINOR: Nueva funcionalidad (compatible) │
│ • Nuevos endpoints │
│ • Campos opcionales agregados │
│ │
│ PATCH: Corrección de bugs │
│ • Sin cambios de API │
│ • Solo fixes internos │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ DEPRECACIÓN: │
│ ───────────── │
│ 1. Anunciar deprecación con anticipación │
│ 2. Agregar header: Deprecation: true │
│ 3. Documentar fecha de sunset │
│ 4. Mantener versión vieja durante transición │
│ 5. Comunicar a consumidores │
└─────────────────────────────────────────────────────────────┘
Documentación de API
Documentación Efectiva
COMPONENTES DE DOCUMENTACIÓN:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. GETTING STARTED │
│ ─────────────────── │
│ • Cómo obtener API key │
│ • Primer request de ejemplo │
│ • Autenticación básica │
│ • Rate limits │
│ │
│ 2. REFERENCIA DE ENDPOINTS │
│ ─────────────────────────── │
│ Por cada endpoint: │
│ • URL y método │
│ • Parámetros requeridos/opcionales │
│ • Ejemplo de request │
│ • Ejemplo de response │
│ • Posibles errores │
│ │
│ 3. GUÍAS DE CASOS DE USO │
│ ────────────────────────── │
│ • "Cómo crear un proyecto" │
│ • "Cómo sincronizar datos" │
│ • Flujos completos, no solo endpoints │
│ │
│ 4. CHANGELOG │
│ ──────────── │
│ • Qué cambió en cada versión │
│ • Breaking changes destacados │
│ • Fechas de deprecación │
│ │
│ HERRAMIENTAS: │
│ ───────────── │
│ • OpenAPI/Swagger para specs │
│ • Postman collections para ejemplos │
│ • README.md para quick start │
│ • Wiki/Docs site para guías │
└─────────────────────────────────────────────────────────────┘
Testing de API
Estrategia de Testing
NIVELES DE TESTING DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. UNIT TESTS │
│ ────────────── │
│ • Lógica de negocio aislada │
│ • Validaciones │
│ • Transformaciones de datos │
│ • Sin dependencias externas │
│ │
│ 2. INTEGRATION TESTS │
│ ───────────────────── │
│ • Endpoint completo │
│ • Base de datos de test │
│ • Happy path + errores │
│ • Autenticación/autorización │
│ │
│ 3. CONTRACT TESTS │
│ ────────────────── │
│ • API cumple contrato documentado │
│ • Request/response schemas │
│ • No romper consumidores │
│ │
│ 4. E2E TESTS │
│ ───────────── │
│ • Flujos completos │
│ • Múltiples endpoints │
│ • Escenarios realistas │
│ │
│ QUÉ TESTEAR EN CADA ENDPOINT: │
│ ────────────────────────────── │
│ ✓ Happy path (éxito) │
│ ✓ Validación de input │
│ ✓ Autenticación requerida │
│ ✓ Autorización (permisos) │
│ ✓ Recurso no encontrado │
│ ✓ Conflictos (duplicados) │
│ ✓ Paginación │
│ ✓ Filtros/búsqueda │
└─────────────────────────────────────────────────────────────┘
Seguridad de API
Consideraciones de Seguridad
SEGURIDAD DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ AUTENTICACIÓN: │
│ ─────────────── │
│ • Bearer tokens (JWT) │
│ • API keys para server-to-server │
│ • OAuth 2.0 para third-party │
│ • Tokens con expiración │
│ │
│ AUTORIZACIÓN: │
│ ────────────── │
│ • Verificar permisos en cada endpoint │
│ • No confiar solo en autenticación │
│ • Principio de mínimo privilegio │
│ • Roles y scopes │
│ │
│ RATE LIMITING: │
│ ─────────────── │
│ • Prevenir abuso │
│ • Límites por usuario/IP │
│ • Headers: X-RateLimit-Remaining │
│ • 429 Too Many Requests │
│ │
│ VALIDACIÓN: │
│ ──────────── │
│ • Validar TODO el input │
│ • Sanitizar para prevenir injection │
│ • Límites en tamaño de payload │
│ • Tipos de contenido permitidos │
│ │
│ HTTPS: │
│ ─────── │
│ • Siempre HTTPS en producción │
│ • No aceptar HTTP │
│ • Certificados válidos │
└─────────────────────────────────────────────────────────────┘