Control de versiones de las API de FedEx

En FedEx, utilizamos versiones semánticas para gestionar las versiones de las API. Cada versión se representa mediante el formato de versión principal.secundaria (por ejemplo, API de envío 1.1). Una nueva versión principal implica que el cambio no es compatible con las versiones anteriores, y una nueva versión secundaria indica un cambio compatible con las versiones anteriores.

En FedEx, seguimos un control de versiones de URI sencillo. Es decir, solo los números de versiones principales se representan en la ruta del URI. Tenga en cuenta que no se incluye en la ruta del URI un número de versión secundaria. Esta estrategia utiliza un enrutamiento URI para identificar versiones concretas de las API.

Ejemplo: /ship/v1/shipments

Principios rectores de la estrategia de control de versiones

Tenemos pensado publicar menos versiones principales para las API de FedEx y retirar una versión principal en dos años a partir de la publicación de la última versión principal. Por ejemplo, se publica «N» de una versión principal, la versión «N-1» se admitirá durante dos años a partir de la publicación de la versión «N».

Ejemplo: en 2020, se publica la versión principal V1.0. Si en 2021 se publica la versión principal V2.0, entonces la V1.0 se retirará en 2023.

Las versiones secundarias admitirán la mayoría de las nuevas funciones y actualizaciones de características.

Ejemplo: se publica la versión principal 1.0, las versiones secundarias 1.1, 1.2, etc. se publicarán para introducir nuevas funciones y actualizaciones de características.

En un momento dado, todos los puntos de conexión de una API concreta tendrán la misma versión principal. La versión más reciente de la documentación solo estará disponible en el FedEx Developer Portal. No obstante, habrá un registro de cambios en cada página de resumen de API, donde se detallarán los cambios de las versiones principales y secundarias.

¿Cuándo se publican las versiones principales de las API?

Trabajamos para reducir al máximo la cantidad de versiones principales de nuestras API. Sin embargo, hay casos en los que es inevitable tener que sacar una versión principal. A continuación se indican algunos de los motivos clave por los que hay que publicar una versión principal:

• Cuando un valor de enumeración existente se elimina, o si ha cambiado su formato o valor en la solicitud o la respuesta
  

  Ejemplo: el valor de enumeración «COORDENADAS GEOGRÁFICAS» para el elemento locationSearchCriterion se elimina en la versión N; la sintaxis de fecha se cambia de YY-MM-DD a MM-DD-YYYY; y el tipo de ubicación de cambia de FEDEX_ONSITE a ONSITE a modo de respuesta.

• Cuando un elemento existente se elimina en la solicitud o la respuesta
  

  Ejemplo: el elemento pickupType se elimina (o se cambia su nombre) de la solicitud de tarifa en la versión N.

• Cuando se elimina un método existente
  

  Ejemplo: el método para crear y cancelar las etiquetas de FedEx Express deja de permitirse en la versión N

• Cuando un elemento existente que antes 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 de FedEx Express® en la versión N

• Cuando hay cambios en el diseño de las API
  

  Ejemplo: la estructura de solicitud y respuesta se ha reorganizado

• Cuando hay cambios con códigos y mensajes de error
  

  Ejemplo: cambiar el código de error de INCORRECT.WEIGHT a WEIGHT.LIMIT.EXCEEDED

¿Cuándo se publican las versiones secundarias de las API?

• Cuando se añade un nuevo valor de enumeración
  

  Ejemplo: se añade una nueva oferta de transporte para el elemento serviceType en la versión N

• Cuando se añade un nuevo elemento
  

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

• Cuando se añada un nuevo método
  

  Ejemplo: se añade un método para modificar documentos comerciales internacionales después de haberse cargado en la versión N.

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

  Ejemplo: el ID de documento ahora es opcional porque FedEx puede derivar el ID de documentación en función de la información del usuario.