Versionado de la API de FedEx

En FedEx, utilizamos el versionado semántico para gestionar las versiones de la API. Cada versión se representa por el formato de la versión de «mayor.menor» (es decir, API de envío 1.1). Una nueva versión mayor significa que el cambio a la inversa es incompatible, mientras que una nueva versión menor indica que un cambio a la inversa es compatible.

En FedEx aplicamos el versionado simple de las URL. Esto involucra solo el número de la versión mayor representado en la ruta URL. Tome en cuenta que no se incluye el número de una versión menor en la ruta URL. Esta estrategia usa el enrutamiento URL para identificar las versiones particulares de la API.

Ejemplo: /ship/v1/shipments

Principios rectores de estrategias de versionado

Planeamos lanzar menos versiones mayores para las API de FedEx y discontinuar una versión mayor en dos años a partir del lanzamiento de una versión mayor más reciente. Por ejemplo, con el lanzamiento de la versión mayor «N», la versión «N-1» seguirá siendo compatible durante dos años a partir del lanzamiento de la versión «N».

Ejemplo: En 2020 se lanzó la versión mayor V1.0. Si en 2021 se lanza la versión V2.0, entonces en 2023 se discontinuará la versión V1.0.

Las versiones menores serán compatibles con la mayoría de las nuevas actualizaciones de funcionalidades y características.

Ejemplo: La versión mayor de POST 1.0 y las versiones menores 1.1, 1.2, etc., se lanzarán para introducir nuevas actualizaciones de funcionalidades y características.

En algún punto del tiempo, todos los extremos para una API particular tendrán la misma versión. La versión más reciente de la documentación solo estará disponible en el FedEx Developer Portal. Sin embargo, habrá un registro de cambios en la página de descripción general de cada API, la cual detallará los cambios de las versiones mayores y menores.

¿Cuándo se lanzarán las versiones mayores de la API?

Nos estamos esforzando por minimizar el número de versiones mayores para nuestras API. Sin embargo, existen ciertos casos en los que una versión mayor es inevitable. Las siguientes son algunas de las razones clave por las que se lanzaría una versión mayor:

• Cuando un valor numerador existente se elimina o formatea, o el mismo valor ha cambiado por solicitud o en respuesta.
  

  Ejemplo: El valor numerador «GEOGRAPHIC_COORDINATES» para el elemento del criterio de búsqueda de localización se elimina en la versión N; la sintaxis de fecha cambió de «AA-MM-DD», a «MM-DD-AAAA»; y cambió el tipo de localización de «FEDEX_ONSITE» a «ONSITE» en respuesta.

• Cuando un elemento existente se elimina por solicitud o en respuesta.
  

  Ejemplo: El elemento de tipo de recolección se eliminó (o renombró) en la solicitud de tarifas en la versión N.

• Cuando se elimina un método existente.
  

  Ejemplo: El método para crear y cancelar etiquetas de FedEx Express ya no es compatible en la versión N.

• Cuando un elemento existente que era opcional o condicional se vuelve obligatorio en la solicitud.
  

  Ejemplo: El número de reserva ahora es un elemento obligatorio para los envíos de carga con FedEx Express® en la versión N.

• Cuando hay cambios en el diseño de la API.
  

  Ejemplo: Se reorganizó la estructura de solicitud y respuesta.

• Cuando hay cambios en los códigos de error y mensajes de error.
  

  Ejemplo: Cambió el código de error de PESO.INCORRECTO a LÍMITE.DE.PESO.EXCEDIDO.

¿Cuándo se lanzarán las versiones menores de la API?

• Cuando se agrega un nuevo valor numerador.
  

  Ejemplo: Se agrega una nueva oferta de transporte para el elemento serviceType en la versión N.

• Cuando se agrega un nuevo elemento.
  

  Ejemplo: Se agrega un nuevo elemento opcional para incluir el número de teléfono del agente para los envíos internacionales.

• Cuando se agrega un nuevo método.
  

  Ejemplo: Se agrega un método para modificar los documentos de comercio internacional después de subirlos en la versión N.

• Cuando un elemento existente que era obligatorio se vuelve opcional.
  

  Ejemplo: La ID del documento ahora es opcional debido a que FedEx puede recuperar la ID de la documentación con base en la información del usuario.