Definition
Deprecación es el anuncio formal de que una característica, endpoint, parámetro o versión de API es obsoleta y será eliminada en una versión futura. Durante el período de deprecación, la característica permanece funcional pero se desaconseja su uso. Esto permite a los consumidores de API migrar a soluciones alternativas sin interrupción inmediata.
La deprecación no es eliminación. Es un estado transicional entre soporte activo y sunset (retiro final). La deprecación efectiva incluye:
- Anuncio claro con cronograma
- Ruta de migración a funcionalidad de reemplazo
- Headers HTTP señalando estado de deprecación
- Actualizaciones de documentación
- Comunicación proactiva a consumidores afectados
Example
Deprecación de API v3 de GitHub:
GitHub deprecó varios endpoints de API REST v3 en favor de GraphQL:
GET /repos/:owner/:repo/events
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://docs.github.com/graphql>; rel="alternate"
Link: <https://docs.github.com/rest/migration>; rel="deprecation"
[
{"id": "12345", "type": "PushEvent"}
]
Estrategia de deprecación:
- Anuncio: 18 meses antes del sunset
- Headers: Fechas de Deprecation + Sunset en cada respuesta
- Documentación: Guía de migración con equivalentes GraphQL
- Monitoreo: Dashboard mostrando uso de endpoints deprecados
- Email: Notificaciones a consumidores de API que aún usan endpoints deprecados
Code Example
# Respuesta de endpoint deprecado
GET /api/v1/users HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 01 Jan 2025 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"
Link: <https://docs.example.com/migration/v1-to-v2>; rel="deprecation"
Warning: 299 - "API v1 está deprecada. Migrar a v2 antes del 2025-01-01"
X-API-Deprecation-Info: https://status.example.com/deprecations/v1
Content-Type: application/json
{
"data": [
{"id": 1, "name": "Alice"}
],
"_deprecation": {
"deprecated": true,
"sunset_date": "2025-01-01",
"replacement": "https://api.example.com/v2/users",
"migration_guide": "https://docs.example.com/migration/v1-to-v2",
"reason": "v2 introduce paginación y filtrado"
}
}
Detección del lado del cliente:
async function fetchUsers() {
const response = await fetch('https://api.example.com/v1/users', {
headers: {
'Authorization': 'Bearer <token>'
}
});
// Verificar headers de deprecación
if (response.headers.get('Deprecation')) {
const sunset = response.headers.get('Sunset');
const migrationGuide = response.headers.get('Link')
?.match(/<([^>]+)>; rel="deprecation"/)?.[1];
console.warn(`API está deprecada. Sunset: ${sunset}`);
console.warn(`Guía de migración: ${migrationGuide}`);
// Registrar en sistema de monitoreo
logger.warn('DEPRECATED_API_USAGE', {
endpoint: '/v1/users',
sunset: sunset,
migrationGuide: migrationGuide
});
}
return response.json();
}
Diagram
graph LR
A[v1 Activa] -->|Nueva característica requiere
cambio de ruptura| B[Desarrollo v2]
B -->|Lanzar v2| C[v2 Activa]
C -->|Anunciar deprecación| D[v1 Deprecada]
D -->|Agregar headers| E[Deprecation: true
Sunset: date]
D -->|Notificar usuarios| F[Campañas email
Advertencias dashboard]
D -->|6-18 meses| G[Período de migración]
G -->|Monitorear uso| H[Rastrear tráfico v1]
H -->|Uso disminuye| I[¿Extender deadline?]
I -->|No| J[Sunset v1]
I -->|Sí| K[Extender 3-6 meses]
K --> G
J -->|Eliminar endpoints| L[v1 Retirada
Respuestas 301/410]
style A fill:#90EE90
style C fill:#90EE90
style D fill:#FFD700
style G fill:#FFD700
style J fill:#FF6B6B
style L fill:#FF6B6B
Best Practices
1. Usar Headers HTTP Estándar
Implementar headers Deprecation: true y Sunset (RFC 8594) en todas las respuestas de endpoints deprecados.
2. Proveer Cronograma Claro Anunciar deprecación con una fecha de sunset específica. Mínimo 12 meses para APIs públicas, 6 meses para APIs internas.
3. Documentar Rutas de Migración Cada característica deprecada debe tener un reemplazo documentado con ejemplos de código mostrando antes/después de la migración.
4. Monitorear Uso Proactivamente Rastrear qué clientes aún usan endpoints deprecados. Contactar directamente a usuarios de alto volumen.
5. Agregar Deprecación al Spec de API
Marcar endpoints como deprecated: true en specs OpenAPI. Herramientas automatizadas pueden detectar uso en tiempo de compilación.
6. Implementar Múltiples Canales de Notificación
- Headers HTTP (detección en tiempo de ejecución)
- Email a consumidores de API registrados
- Notificaciones in-app (si tienes dashboard)
- Changelog y posts de blog
- Anuncios en página de estado
7. Degradación Gradual (Opcional) Opcionalmente reducir rate limits para endpoints deprecados para fomentar migración (ej., 1000 req/min → 100 req/min).
8. Nunca Extender Deadlines de Último Minuto Si debes extender, anúncialo al menos 3 meses antes de la fecha de sunset original.
Common Mistakes
1. Deprecar Sin Reemplazo Eliminar funcionalidad sin proveer alternativa fuerza a consumidores a abandonar características o cambiar de proveedor.
2. Período de Aviso Insuficiente Deprecar con solo 1-3 meses de aviso no da a clientes enterprise tiempo para planificar sprints y desplegar cambios.
3. Deprecación Silenciosa Solo actualizar documentación sin headers HTTP o notificaciones por email significa que muchos consumidores no se darán cuenta hasta que sea tarde.
4. Sin Rastreo de Uso Deprecado Hacer sunset de un endpoint sin verificar métricas de uso puede romper integraciones críticas aún en uso activo.
5. Eliminar Características Deprecadas Muy Pronto Algunos clientes legítimamente necesitan más tiempo. Monitorear uso y extender deadlines si una porción significativa aún depende de características deprecadas.
6. Políticas de Deprecación Inconsistentes Diferentes equipos usando diferentes cronogramas crea confusión. Estandarizar políticas en toda la organización.
7. Romper Compatibilidad Durante Deprecación Las características deprecadas deben permanecer completamente funcionales hasta el sunset. No introducir bugs o reducir funcionalidad durante el período de deprecación.