ADR-005: Estrategia de Versionado de APIs¶
Estado: PROPUESTO Fecha: 2025-12-07 Autor: ApiContractDrone (MTS-DRN-API-001) Revisores: SpecQueen, Director
1. Contexto¶
MedTime tendra multiples clientes (iOS, Android, Web) que pueden no actualizarse simultaneamente. Necesitamos:
- Soportar versiones antiguas de clientes
- Introducir breaking changes de forma segura
- Comunicar deprecaciones claramente
- Mantener compatibilidad hacia atras por periodo razonable
2. Decision¶
Adoptamos URL Path Versioning con politica de soporte de 2 versiones.
2.1. Formato de URL¶
2.2. Politica de Versionado¶
| Tipo de Cambio | Accion |
|---|---|
| Agregar campo opcional | No bump de version |
| Cambiar tipo de campo | Nueva version (v1 → v2) |
| Remover campo | Nueva version + deprecation |
| Nuevo endpoint | No bump de version |
| Cambio de comportamiento | Nueva version |
2.3. Ciclo de Vida¶
2.4. Headers de Deprecacion¶
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: </v2/medications>; rel="successor-version"
3. Consecuencias¶
3.1. Positivas¶
- Claridad: Version explicita en URL
- Cache-friendly: Diferentes URLs = diferentes recursos
- Documentacion simple: Swagger por version
- Flexibilidad: Breaking changes controlados
3.2. Negativas¶
- Mantenimiento: Multiples versiones de codigo
- Complejidad: Logica de routing por version
3.3. Riesgos¶
- Clientes desactualizados: Usuarios con apps viejas
- Mitigacion: Force update para versiones muy viejas, notificaciones in-app
4. Alternativas Consideradas¶
4.1. Header Versioning¶
- Rechazado porque: Menos visible, problemas de cache
4.2. Query Parameter Versioning¶
- Rechazado porque: Menos estandar, propenso a errores
4.3. No Versioning (siempre compatible)¶
- Rechazado porque: Limita evolucion de API
5. Referencias¶
- API Versioning Best Practices
- functional-spec/11-estandares-api.md
- OpenAPI 3.0 Specification
ADR generado por ApiContractDrone - IT-01