A medida que nuestra API evoluciona, se pueden producir cambios importantes o "breaking changes" que pueden impactar a tu integración.Cada día existen actualizaciones de las aplicaciones que utilizamos en nuestros dispositivos móviles y computadoras. Y nuestro código no está exento de estas actualizaciones. Ya sea para corregir un error o para actualizar una funcionalidad, el versionamiento nos permite ofrecer nuevas funcionalidades y mejoras sin afectar las integraciones anteriores.Cuando hablamos de aplicaciones móviles o de escritorio es posible lanzar nuevas versiones y parches con cambios menores, medianos y grandes. No obstante, en el caso del API no es posible ofrecer múltiples versiones simultaneas y mantenerlas indefinidamente para todos sus usuarios. Con base en este contexto, se establece el concepto de un cambio importante breaking change.Breaking changes#
Un cambio importante o breaking change, es un cambio que puede requerir que realices cambios en tu aplicación para evitar interrupciones en tu integración.Estos tipos de cambios se notificarán con antelación a tu comercio para que pueda realizar cualquier actualización requerida con tiempo y que no exista interferencias en el servicio.Si nos encontramos con algún error de seguridad o un bug que podría afectar de manera importante al correcto funcionamiento de nuestro producto realizaremos los cambios a la mayor brevedad posible, dentro del acuerdo de nivel de servicio.
Cambios a permisos existentes
Remover un parámetro, campo de respuesta o de petición previamente permitido.
Agregar un nuevo parámetro o campo de petición que sea requerido y que no tendrá valores por defecto. Esto podría cambiar la interacción al llamar a una función ya que al no poseer el numero de campos necesarios en la petición no obtendremos respuesta o tendremos un error como respuesta
Cambios a la funcionalidad final de un endpoint
Agregar una nueva validación
Remover o renombrar un endpoint, campo o valor enum
Cambiar el tipo de un campo
Cambiar el formato del URL en la definición del HTTP
Cambiar a un campo opcional a que sea requerido en la petición
Non-breaking changes#
En contraste, los non-breaking changes son cambios a los cuales te podrás adaptar a tu discresión y ritmo sin tener intermitencias en tu integración. En la mayoría de los casos estos se presentan sin previa notificación. Asegúrate que tu aplicación o integración esta diseñada para manejar este tipo de cambios.En términos generales si realizamos un cambio catalogado como "non breaking", el servicio o producto actual seguirá trabajando normalmente sin la necesidad de realizar actualizaciones en la integración.Estos son los cambios que podríamos realizar sin considerar que podrían afectar la integración:Agregar un nuevo endpoint
Agregar un nuevo método a un endpoint existente
Agregar nuevos campos en los siguientes escenarios:Nuevos campos en respuestas
Nuevo campo de petición o parámetros opcionales
Nuevo campo de petición requerido que tendrá valores por defecto
Agregar un nuevo valor devuelto por un campo de texto existente
Cambios en el orden que son retornados los campos de respuesta
Agregar un header de petición opcional
Remover campos redundantes del header
Cambios a la longitud de la información devuelta por un campo
Cambios del tamaño promedio de la respuesta
Cambios a los mensajes de error. (Recomendamos parsear los códigos de respuesta o error v/s parsear el mensaje de error directamente en tu integración)
Cambios en los códigos de respuesta o de error pasando de un valor incorrecto a uno correcto
Añadir un nuevo valor a una enumeración o enum
