API Versioning
Versionado de la API
El versionado de la API es un plan para nombrar, cambiar, soportar y retirar los contratos de API sin romper los clientes. No existe una URL o estilo de encabezado único que toda API deba usar.
Otro ejemplo
Una API de nómina publica el contrato OpenAPI `2026-07` y mantiene a los clientes de `/v1` funcionando. Agregar un campo opcional no los rompe. Cambiar `netPay` de centavos enteros a un decimal necesita un nuevo contrato mayor. También requiere guías de migración, encabezados de desaprobación, datos de uso y una fecha de retiro.
Partes principales
- 01Identificador de contrato
- 02Reglas de compatibilidad
- 03Desaprobación y migración
Úsalo cuando
Establece reglas de compatibilidad, cambia tipos, el método de descubrimiento, el período de soporte y la política de desuso primero. Luego elige una ruta, tipo de medio o estilo de encabezado.
No lo uses cuando
No cree una nueva versión de la API para cada lanzamiento. No prometa soporte indefinidamente sin datos de uso y una manera de retirar versiones antiguas.
Nombre usado en código
explicit compatibility policy + versioned OpenAPI document + deprecation and sunset lifecycle Antes de lanzarlo
Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback.
Outcome: Complete the task with Versionado de la API (API Versioning). User context: Una API de nómina publica el contrato OpenAPI `2026-07` y mantiene a los clientes de `/v1` funcionando. Agregar un campo opcional no los rompe. Cambiar `netPay` de centavos enteros a un decimal necesita un nuevo contrato mayor. También requiere guías de migración, encabezados de desaprobación, datos de uso y una fecha de retiro. Technical concept or control: Versionado de la API (API Versioning). Why it fits: Establece reglas de compatibilidad, cambia tipos, el método de descubrimiento, el período de soporte y la política de desuso primero. Luego elige una ruta, tipo de medio o estilo de encabezado. Do not use it when: No cree una nueva versión de la API para cada lanzamiento. No prometa soporte indefinidamente sin datos de uso y una manera de retirar versiones antiguas. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): Ningún estándar oficial único controla todo el término. Su significado puede cambiar según equipos, plataformas o marcos. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.
Revisa esta petición
Review how Versionado de la API (API Versioning) is used now. Definition: El versionado de la API es un plan para nombrar, cambiar, soportar y retirar los contratos de API sin romper los clientes. No existe una URL o estilo de encabezado único que toda API deba usar. Release checks: Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback. Before changing code, list the evidence, gaps, severity, and the smallest safe fix.