Política de cambios importantes del API

16 julio 2022

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 estable 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.

Comunicaremos este tipo de cambios con una antelación de al menos 4 meses para que realices actualizaciones necesarias antes de que saquemos una nueva versión a producción.

Estos cambios los podemos catalogar dentro de los siguientes:

• 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