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) ySunset(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.