Versionado

​

Cómo funciona el control de versiones

• Cuando se agregan nuevos puntos finales a la API, todas las versiones de API existentes pueden acceder a ellos de forma predeterminada. Esto garantiza que se puedan adoptar nuevas funciones sin necesidad de cambios inmediatos en los números de versión.
• Las integraciones que utilizan OAuth 2.0 utilizarán automáticamente la última versión de API al obtener un token de acceso, a menos que se especifique una versión específica en el encabezado de la solicitud.

​

Versión API actual

• Versión en uso: v1.0 es la única versión publicada y todas las solicitudes de API deben utilizarla. Esto garantiza la compatibilidad y el acceso a las características y funcionalidades más recientes admitidas en la versión v1 de nuestra API.
• Ejemplo: GET /api/p/v1/{resource}
  Reemplace {resource} con el punto final específico al que está llamando, como drivers, loads, etc.

​

Comprender el control de versiones semántico

• Versión principal (por ejemplo v1): introducida para cambios incompatibles con versiones anteriores. Los ejemplos incluyen eliminar o cambiar el nombre de campos, cambiar estructuras de respuesta o alterar funcionalidades existentes que podrían romper las integraciones existentes.
• Versión secundaria (v1.1, v1.2): se utiliza para agregar o mejorar funciones compatibles con versiones anteriores que no interrumpen la funcionalidad existente. Los ejemplos incluyen agregar nuevos parámetros o puntos finales opcionales.
• Versión de parche (v1.0.1, v1.0.2): Emitido para correcciones de errores compatibles con versiones anteriores o cambios menores que no afectan la funcionalidad de la API.

​

Cambiar versiones de API

• Parámetros de ruta: para puntos finales específicos, debe proporcionar la clave de versión en la ruta, por ejemplo, /api/{controller}/{version}/action.
• Encabezado HTTP: las versiones se pueden anular proporcionando el encabezado api-version HTTP con su solicitud. Recomendamos pasar siempre este valor de encabezado para sus solicitudes de API para confirmar que su integración utiliza la versión de API prevista.

​

Ejemplo de formato de URL

• Punto final básico con versión en URL: https://integrations.alvys.com/api/p/v1/drivers
• Para configurar explícitamente la versión a través del encabezado HTTP:
  GET /drivers
  Host: integrations.alvys.com
  api-version: v1
  

​

Cambios incompatibles hacia atrás

• Agregar campos obligatorios del cuerpo de la solicitud, valores de los campos del cuerpo de la solicitud o parámetros de consulta.
• Eliminación de campos de cuerpo de solicitud permitidos, valores de campos de cuerpo de solicitud, parámetros de consulta o valores de parámetros de consulta.
• Reducir los límites de solicitudes documentados por punto final, por token o por organización.
• Cambiar el nombre de los campos del cuerpo de la solicitud/respuesta, los valores de los campos del cuerpo de la solicitud, los parámetros de consulta o los valores de los parámetros de consulta.
• Cambiar el nombre o eliminar valores válidos para campos enumerados (por ejemplo, diferentes opciones para tipos de eventos de seguridad).
• Cambiar el tipo de datos de un campo (por ejemplo, de cadena a int).
• Cambiando la estructura anidada JSON de solicitudes/respuestas.
• Cambiar la carga útil esperada de una respuesta (por ejemplo, devolver conductores activo e inactivo en lugar de solo activo).
• Desaprobar el acceso a ciertos puntos finales.

​

Cambios compatibles con versiones anteriores

• Cambiar el mensaje de error de un punto final API.
• Cambiar la estructura del valor de cadena de un campo devuelto en el cuerpo de una respuesta.
• Introduciendo campos de estructura opcionales adicionales (que admiten valores NULL).