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. Así sea por corregir un error o 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. En base a 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 que es un no breaking change 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 próximos 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 correcto.
  • Añadir un nuevo valor a una enumeración o enum.