Versionado y deprecaciones
Qué puede cambiar sin avisarte, y qué no.
La versión va en la ruta: todas las operaciones de la API pública están bajo
/api/v5/rest/. Mientras ese número no cambie, lo que ya funciona sigue
funcionando.
No hay que mandar ningún header de versión. No hay versiones por fecha ni por organización: en un momento dado hay una sola API pública, y es la que describe este portal.
Qué se considera un cambio compatible
Estos cambios pueden aparecer en cualquier momento, y tu integración tiene que tolerarlos:
- Campos nuevos en una respuesta. Parseá el JSON ignorando lo que no conocés; no valides que la respuesta tenga exactamente las claves que esperabas.
- Parámetros opcionales nuevos en un endpoint que ya existía.
- Endpoints nuevos, y secciones nuevas en la referencia.
- Cambios en
messageydetail. Son textos para que los lea una persona. Ramificá por el status HTTP, como dice la guía de errores.
Qué no cambia en silencio
Nada que pueda romper una integración andando: quitar un campo de la respuesta, volver requerido un parámetro que era opcional, cambiar el tipo de un campo, mover una ruta o retirar un endpoint.
Todo eso se publica en el changelog antes o el mismo día en que sale. Si un cambio afecta el contrato y no está ahí, es un error nuestro — contános.
El camino de una deprecación
Un endpoint no desaparece de un día para el otro. Pasa por tres etapas, y en todas sigue respondiendo igual:
Se marca como deprecado
Aparece con la etiqueta Deprecated en la referencia, y su página dice cuál es el reemplazo. La llamada sigue funcionando exactamente como antes.
La consecuencia práctica: si un endpoint que usás quedó marcado como deprecado, no es una urgencia. Pero tampoco lo dejes para siempre — migrá cuando toques esa parte del código, porque los reemplazos suelen traer paginación y la envoltura estándar, que el viejo no tenía.
Cómo enterarte
El changelog es la fuente. Lista endpoints nuevos, deprecaciones, cambios de comportamiento y de formato de respuesta; los cambios internos que no alteran el contrato no se listan, así que lo que hay ahí es todo lo que te puede afectar.
Tiene un botón Subscribe via RSS arriba a la derecha: si tu equipo ya lee feeds en Slack o en un lector, es la forma más barata de no tener que venir a mirar.