Saltar a contenido

Política de deprecación de la API /v1

Esta página describe cómo retiramos o cambiamos de forma incompatible lo publicado bajo /v1.

Qué cuenta como cambio incompatible

Son incompatibles:

  • eliminar o renombrar un endpoint, un campo o un parámetro;
  • cambiar el tipo, la unidad o el significado de un campo;
  • exigir una entrada nueva obligatoria, o aceptar menos de lo que se aceptaba;
  • cambiar la autenticación o los scopes que exige una operación.

No son incompatibles y pueden llegar a /v1 sin este plazo: nuevos endpoints, nuevos campos opcionales en las respuestas, nuevos parámetros opcionales y nuevos valores en vocabularios abiertos (por ejemplo status o severity). Tu cliente debe tolerar campos y valores desconocidos.

Nuestros compromisos

  • Al menos 12 meses entre el aviso de deprecación y la retirada o el cambio incompatible.
  • Un correo a quien creó cada clave de API activa afectada (ni revocada ni caducada), si sigue siendo miembro activo de la organización, y a los administradores del inquilino al que pertenece la clave. Nadie recibe el aviso dos veces.
  • Cabeceras HTTP. Cuando retiremos algo, las respuestas de los endpoints afectados incluirán Deprecation (RFC 9745) y Sunset (RFC 8594) con la fecha de retirada.
  • Una entrada en el changelog, con la fecha del aviso y la de retirada.

Excepción de seguridad

Una corrección de seguridad puede romper un comportamiento de /v1 antes de que pasen 12 meses. En ese caso daremos el mayor aviso posible, avisaremos por correo a los mismos destinatarios y explicaremos el motivo en el changelog.

Una excepción anunciada antes de esta política

Los valores en español del filtro severity de GET /v1/alerts (critico, alto, medio, bajo) se anunciaron para su retirada antes de que existiera esta política. Su fecha, 2027-01-14, no cambia. Cambia a los valores en inglés (critical, high, medium, low, info) antes de esa fecha.

Entrada en vigor

Esta política entra en vigor el día en que se publica esta página; lo ya decidido antes sale con el régimen anterior: el 400 ante parámetros de consulta desconocidos y la retirada de los valores en español de severity.

Fuera de alcance

Los webhooks y los límites de uso quedan fuera de esta política; tienen su propio ciclo.

Cómo mantenerte informado

Consulta el changelog y la sección «Contract changes» de GET /v1/openapi.json, y vigila las cabeceras Deprecation y Sunset de las respuestas.