Política de cambios importantes del API

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