Control de versiones de la API
Cómo evoluciona la API de Diveity — qué cambios afectan a los clientes y cómo los comunicamos.
Reglas de compatibilidad con versiones anteriores
Estas reglas describen qué es seguro y qué es un cambio importante en cada endpoint de /api/v1.
Campos de respuesta
- Añadir un campo no es un cambio importante — los clientes ignoran los campos desconocidos.
- Eliminar un campo es un cambio importante — requiere una nueva versión de la API.
- Renombrar un campo es un cambio importante — requiere una nueva versión de la API.
- Cambiar el tipo de un campo (p. ej., cadena → número) es un cambio importante — requiere una nueva versión de la API.
Parámetros de consulta
- Añadir un parámetro de consulta OPCIONAL no es un cambio importante.
- Eliminar un parámetro de consulta opcional es un cambio importante — los clientes que dependen de él pierden funcionalidad silenciosamente.
Política de deprecación
Cuando lanzamos una nueva versión principal de la API, la versión anterior entra en una ruta de finalización documentada.
- Aviso mínimo de 6 meses entre el anuncio de deprecación y el fin de vida útil.
- Durante el período de deprecación, cada respuesta incluye el encabezado de Deprecación RFC 9745 (?1) y el encabezado Sunset RFC 8594 (fecha HTTP de EOL).
- 30 días antes de la finalización, comienzan los 'brownouts': una pequeña fracción de las solicitudes devuelve 503 Servicio no disponible para detectar integraciones persistentes. La fracción aumenta del 0% al 25% durante el período.
- Los desarrolladores cuyas claves de API accedieron a una versión deprecada en los 30 días anteriores reciben un correo electrónico una vez por cada transición de versión principal.
- Después de la fecha de finalización, la versión se elimina; las solicitudes a ella devuelven 404.