API Deprecation: Definición, Mejores Prácticas, Ejemplos

¿Qué es API deprecation?

API deprecation es el proceso formal de eliminar gradualmente un endpoint API, versión, parámetro o campo response. El thing deprecated sigue funcionando durante un período sunset, pero los consumers son advertidos a migrar. Eventualmente, el piece deprecated es removido (llamado "sunset"), y los clientes que aún lo llaman se rompen.

Deprecation es el contrato entre API provider y consumers: "Estamos cambiando esto. Aquí está el timeline. Aquí está la alternativa."

Lifecycle deprecation

Estándares HTTP para deprecation

HTTP/1.1 200 OK
Deprecation: Sat, 1 Jun 2026 00:00:00 GMT
Sunset: Sat, 1 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

Qué se deprecateа

• Versiones API enteras
• Endpoints específicos
• Parámetros request
• Campos response
• Métodos autenticación
• Tipos eventos webhook
• Métodos SDK

Mejores prácticas deprecation

• Anunciar temprano.
• Documentar path migración.
• Usar headers Sunset/Deprecation.
• Email consumers conocidos.
• Trackear uso.
• Período transición con ambas APIs corriendo.
• Estrategia versioning.
• Documentar changelog.
• Brownouts antes sunset.

Pitfalls deprecation comunes

• Breakage silencioso.
• Sin path migración documentado.
• Ventana sunset muy corta.
• Remover campo aún en uso.
• Olvidar SDKs.
• Sin reemplazo.
• Comunicación solo via blog.

Ejemplo: deprecation API GitHub

GitHub anuncia breaking changes ~12 meses por adelantado.

Ejemplo: versioning API Stripe

Stripe pinea cada API key a una fecha versión específica.

FAQ: API deprecation

¿Cuán larga debería ser una ventana sunset?

6+ meses para cambios pequeños; 12+ meses para version cuts mayores.

¿Debería versionar mi API?

Sí para cualquier API con consumers externos.

¿Diferencia entre deprecation y sunset?

Deprecation: anunciado. Sunset: realmente removido.

¿Cómo sé quién llama mi API deprecated?

Loguear uso per-endpoint con consumer ID.

¿Qué código HTTP para endpoints sunset?

410 Gone.

¿Debería deprecar o solo añadir nuevos campos?

Cambios aditivos son non-breaking.

¿Qué si los customers no migran?

Brownouts antes sunset final.

Testea coexistencia versión API con LoadFocus

Durante ventanas deprecation, LoadFocus corre scripts JMeter y k6 contra versiones API viejas y nuevas. Regístrate en loadfocus.com/signup.