Saltar al contenido principal

Política de versiones y deprecación

Versionado​

La versión mayor va en la ruta: hoy /api/v1. Dentro de una versión mayor solo hacemos cambios compatibles; lo que rompa a un cliente existente requiere una versión nueva (/api/v2).

Cambios compatibles (sin aviso previo)​

  • Endpoints, parámetros opcionales y ámbitos nuevos.
  • Campos nuevos en respuestas JSON y en el data de los webhooks.
  • Eventos de webhook nuevos.
  • Códigos de error nuevos para situaciones que antes no existían.
  • Correcciones de comportamiento que alinean la API con lo documentado.

Escribe tu cliente para ignorar campos desconocidos y no depender del orden de las propiedades.

Cambios incompatibles (con aviso)​

  • Quitar o renombrar un endpoint, campo, parámetro, ámbito o evento.
  • Cambiar el tipo o el significado de un campo.
  • Hacer obligatorio un parámetro que era opcional.
  • Cambiar el esquema de firma de los webhooks.

Deprecación​

  1. Anuncio. Se marca como deprecado en el changelog con la fecha de retirada. La respuesta de los endpoints afectados incluye las cabeceras Deprecation y Sunset cuando es técnicamente posible.
  2. Aviso mínimo de 12 meses entre el anuncio y la retirada. Durante ese periodo la función sigue funcionando igual.
  3. Retirada. Pasada la fecha, el endpoint puede responder 410 Gone.

Excepción: una vulnerabilidad de seguridad puede obligar a un plazo menor. Se comunicaría igualmente por el changelog y a los administradores de la cuenta.

Firma de webhooks​

La firma lleva prefijo de versión (v1=). Si cambia el esquema, se anunciará con el mismo plazo de 12 meses y ambos esquemas convivirán durante ese tiempo. Compara siempre el prefijo antes de validar.

Relacionado​