Compatibilidad
Compatibilidad
Qué podemos cambiar en v1 sin aviso y qué exigiría una nueva versión mayor. Se enuncia como lista enumerada y no como promesa, para que una integración pueda blindarse exactamente contra el conjunto correcto.
Las rutas, los métodos, los ámbitos, los nombres de campo y los códigos de error se publican en inglés, porque el inglés es el idioma de la propia interfaz: es lo que quien llama escribe o compara. Lo mismo ocurre con cada ejemplo de código, cada carga JSON y la frase exacta que lleva una respuesta de error: /v1 no lee Accept-Language, y traducir lo que la API envía realmente sería describirla mal. Todo lo que se escribe sobre ello sigue el idioma de esta página.
La revisión actual es 2026-08-01. La ruta sigue siendo /v1; la revisión identifica el documento que la describe.
Cambios que no haremos en v1
Estos exigen una nueva versión mayor. Si alguna vez necesitáramos una, las versiones existentes seguirían respondiendo durante la migración.
- Eliminar una operación.
- Eliminar o renombrar un parámetro, o un campo de una respuesta.
- Añadir un parámetro obligatorio nuevo.
- Convertir en obligatorio un parámetro que antes era opcional.
- Cambiar el tipo de un parámetro o de un campo de respuesta.
- Eliminar un valor de una enumeración.Un cliente que ramifica según ese valor no tiene ninguna rama para su ausencia, así que falla del modo en que su lenguaje falle ante un caso no contemplado.
- Añadir una regla de validación nueva a un parámetro existente.Una solicitud que ayer funcionaba empezaría a fallar, y eso es una retirada de capacidad disfrazada de corrección de errores.
- Cambiar los requisitos de autenticación o de autorización, incluido el ámbito que exige una operación.
Cambios que podemos hacer en cualquier momento
Su integración debe tolerarlos todos. Van a ocurrir, y no se anunciarán.
- Añadir una operación nueva.
- Añadir un parámetro opcional nuevo.
- Añadir una cabecera de solicitud opcional nueva.
- Añadir un campo nuevo a una respuesta.Interprete las respuestas con tolerancia: un cliente que rechace campos desconocidos se romperá con la primera adición que hagamos.
- Añadir una cabecera de respuesta nueva.
- Añadir un valor a una enumeración.Trate un valor no reconocido como un caso por defecto y no como un error. Aparecerán categorías de pasaporte nuevas y tipos de evento nuevos.
- Subdividir un código de error en otros más precisos, pero solo cuando el original no podía resolverse con lógica en tiempo de ejecución, como un reintento.Dividir un código por el que un cliente RAMIFICA es un cambio incompatible; dividir uno que solo se registra en el log, no. La distinción está en si el comportamiento dependía de él.
Lo que su cliente debe tolerar
Cada uno de estos puntos corresponde a un cambio de los de arriba que nos reservamos el derecho de hacer. Un cliente que incumpla alguno se romperá con algo que nosotros consideramos rutina.
- Ignore los campos de respuesta que no reconozca, en lugar de rechazar la respuesta.
- Trate un valor de enumeración no reconocido como un caso por defecto, no como un error.
- Trate los identificadores como cadenas opacas; nunca los interprete ni los compare con un patrón.
- No dependa del ORDEN de los campos dentro de un objeto JSON ni de la redacción exacta de un mensaje de error legible por personas. Ramifique por el código de error legible por máquina.
- Reintente ante un 429 y ante cualquier otro rechazo que lleve una cabecera Retry-After, esperando el tiempo que indique. No es una cabecera exclusiva del 429: un 409 resource_busy, un 503 storage_unavailable y un 503 entitlement_unavailable también la llevan, porque en ellos reintentar es la solución.
- Reintente un 5xx con una Idempotency-Key NUEVA. Una clave que registró un error del servidor reproduce ese error durante toda la ventana de retención, y lo hace a propósito: el fallo pudo ser una respuesta perdida de una escritura que SÍ funcionó, y reutilizar la clave es lo que impide que una escritura fallida acabe siendo dos.
- Vigile las cabeceras de respuesta Deprecation y Sunset, y el Link: rel="successor-version" que las acompaña. Así se anuncia la retirada de un endpoint, y llega mucho antes de que el endpoint deje de responder.
Trate cada identificador como una cadena opaca de 255 caracteres como máximo. No los interprete, no valide su formato y no dé por hecho que son UUID: el formato puede cambiar sin aviso.
Obsolescencia
Un endpoint destinado a desaparecer responde con cabeceras Deprecation y Sunset, además de una cabecera Link que nombra a su sucesor. Llegan mucho antes de que el endpoint deje de responder. Vigílelas.