Cómo hacer que sus API REST sean compatibles con versiones anteriores

La transferencia de estado representacional, comúnmente conocida como REST, es un estilo arquitectónico: un conjunto de restricciones que se utilizan para implementar servicios sin estado que se ejecutan en HTTP. Una API RESTful es aquella que se ajusta a las restricciones REST. Puede crear API RESTful utilizando muchos lenguajes de programación diferentes.

Mantener la compatibilidad con versiones anteriores entre las diferentes versiones de su API es de suma importancia para garantizar que su API seguirá siendo compatible con todos los clientes que la consumen. Este artículo presenta una discusión sobre cómo puede mantener la compatibilidad con versiones anteriores en sus API RESTful.

Ejemplo de compatibilidad de API

Suponga que tiene una API en producción que está siendo consumida por diferentes clientes. Ahora, si desea agregar más funcionalidad a la API, debe asegurarse de que los clientes que usan la API anterior puedan usar la API nueva o la anterior. En otras palabras, debe asegurarse de que la funcionalidad existente de la API permanezca intacta mientras se agrega la nueva funcionalidad.

Una API es compatible con versiones anteriores si un cliente (un programa escrito para consumir la API) que puede funcionar con una versión de la API puede funcionar de la misma manera con versiones futuras de la API. En otras palabras, una API es compatible con versiones anteriores entre versiones si los clientes deberían poder trabajar con una nueva versión de la API sin problemas.

Entendamos esto con un ejemplo. Suponga que tiene un método de API llamado GetOrders como se muestra en el fragmento de código a continuación.

[HttpGet]

[Ruta ("GetOrders")]

 public IActionResult GetOrders (int customerId, int orderId = 0)

 {

   var result = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   return Ok (resultado);

 }

El método de acción GetOrders acepta un ID de cliente y un ID de pedido como parámetros. Tenga en cuenta que el segundo parámetro, orderID, es opcional. El método privado GetOrdersForCustomer se proporciona a continuación.

Private List GetOrdersForCustomer (int customerId, int orderId)

{

   // Escriba el código aquí para devolver uno o más registros de pedidos

}

El método GetOrdersForCustomer devuelve todos los pedidos de un cliente si el orderId que se le pasó como parámetro es 0. Si el orderId no es cero, devuelve un pedido perteneciente al cliente identificado por el customerId pasado como argumento.

Dado que el segundo parámetro del método de acción GetOrders es opcional, simplemente puede pasar el customerId. Ahora, si cambia el segundo parámetro del método de acción GetOrders para hacerlo obligatorio, los antiguos clientes de la API ya no podrán utilizar la API.  

[HttpGet]

[Ruta ("GetOrders")]

 public IActionResult GetOrders (int customerId, int orderId)

 {

   var result = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   return Ok (resultado);

 }

¡Y así es exactamente como puede romper la compatibilidad de su API! La siguiente sección analiza las mejores prácticas que se pueden adoptar para hacer que su API sea compatible con versiones anteriores.

Consejos de compatibilidad con API

Ahora que sabemos de qué se trata el problema, ¿cómo diseñamos nuestras API de la manera recomendada? ¿Cómo nos aseguramos de que nuestra API RESTful sea compatible con versiones anteriores? Esta sección enumera algunas de las mejores prácticas que se pueden seguir a este respecto. 

Asegúrese de que pasen las pruebas unitarias

Debe tener pruebas escritas que verifiquen si la funcionalidad está intacta con una nueva versión de la API. Las pruebas deben estar escritas de tal manera que fallen si hay algún problema de compatibilidad con versiones anteriores. Idealmente, debería tener un conjunto de pruebas para las pruebas de API que fallará y alertará cuando haya problemas con la compatibilidad con versiones anteriores de la API. También podría tener un conjunto de pruebas automatizado conectado a la canalización de CI / CD que verifica la compatibilidad con versiones anteriores y alerta cuando hay una infracción.

Nunca cambie el comportamiento de los códigos de respuesta HTTP

Nunca debe cambiar el comportamiento de los códigos de respuesta HTTP en su API. Si su API devuelve 500 cuando no se puede conectar a la base de datos, no debe cambiarlo a 200. De manera similar, si está devolviendo HTTP 404 cuando ocurre una excepción, y sus clientes están usando esto y el objeto de respuesta para identificar qué sucedió. incorrecto, cambiar este método de API para devolver HTTP 200 romperá la compatibilidad con versiones anteriores por completo.

Nunca cambie los parámetros

Evite crear una nueva versión de la API cuando realice solo cambios menores, ya que podría ser excesivo. Un mejor enfoque es agregar parámetros a sus métodos de API para incorporar el nuevo comportamiento. Del mismo modo, no debe eliminar parámetros de un método de API o cambiar un parámetro de opcional a obligatorio (o viceversa), ya que estos cambios romperán la API y los clientes o consumidores antiguos de la API ya no podrán para trabajar con la API.

Versión de su API

El control de versiones de las API es una buena práctica. El control de versiones ayuda a que su API sea más flexible y adaptable a los cambios mientras mantiene la funcionalidad intacta. También le ayuda a administrar mejor los cambios en el código y volver más fácilmente al código anterior si el nuevo código causa problemas. Debería tener una versión diferente de su API RESTful con cada versión principal.

Aunque REST no proporciona ninguna guía específica sobre el control de versiones de API, puede versionar su API de tres formas diferentes: especificando la información de la versión en el URI, almacenando la información de la versión en el encabezado de la solicitud personalizada y agregando la información de control de versiones al HTTP Accept encabezamiento. Aunque el control de versiones puede ayudarlo a mantener su API, debe evitar intentar mantener muchas versiones de la API para marcar lanzamientos frecuentes. Esto rápidamente se volverá engorroso y contraproducente. 

Otras mejores prácticas de API

Nunca debe cambiar la URL raíz de una API ni modificar los parámetros de la cadena de consulta existente. Cualquier información adicional debe agregarse como un parámetro opcional a un método API. También debe asegurarse de que los elementos opcionales u obligatorios que se pasan a una API o se devuelven desde una API nunca se eliminen.

Los cambios en una API RESTful son inevitables. Sin embargo, a menos que se adhiera a las mejores prácticas y se asegure de que la API sea compatible con versiones anteriores, sus cambios pueden romper la compatibilidad de la API con los clientes existentes. Una API que está en producción y está siendo consumida por varios clientes siempre debe ser compatible con versiones anteriores entre versiones.