Versiones en nuestra API REST

Una de las cosas que hay que tener en cuenta cuando hacemos una API es que esta, al igual que otro tipo de aplicaciones web, va a cambiar.

Si la API es pública o es consumida por una gran cantidad de clientes, es casi seguro que muchos de estos clientes queden obsoletos o no sigan al día las actualizaciones que tu equipo vaya haciendo en la misma.

La solución consiste en dar compatibilidad a las versiones anteriores y de alguna forma separar o que el cliente pueda indicar a qué versión está accediendo en cada momento.

Las opciones más habituales para hacer esto serían:

Indicar la versión de la API en la URL del recurso.

https://api.dominio.com/v1/recurso/

Este sería un ejemplo de URL en la que se indica la versión de la API en la misma.

Esta es la opción más aconsejada pero la que a mí personalmente menos me convence ya que los clientes que quisieran estar actualizados a la última versión, deberían modificar las rutas de sus llamadas al servicio constantemente.

Indicar como parámetro la versión de la API

https://api.dominio.com/recurso/?v=1

Este tipo de opción se usa por ejemplo en la API de YouTube.

Yo personalmente prefiero indicar como parámetros opciones para filtrar o tratar la información del recurso solicitado. Por ejemplo, paginaciones, órdenes, búsquedas, especificar información parcial etc.

Indicar como header la versión de la API

https://api.dominio.com/recurso/ 
“API version”: 1

Esta opción es la que más me convence, ya que no se ensucia la URL y si la aplicación cliente tiene las llamadas centralizadas en un único punto no debería ser problema añadir un header extra indicando la versión del API.

Después en el servidor podremos separar las versiones de las APIs en distintos servidores web o aplicaciones mediante un servidor proxy HTTP como Varnish que lea el header del request y sirva la versión de la API solicitada de forma transparente.

En javascript por ejemplo tendríamos el siguiente código para añadir un header http a nuestra llamada AJAX.


var request = new XMLHttpRequest();
request.open("GET", "https://api.dominio.com/recurso/", false);
request.setRequestHeader("API version", "1");
request.send();

En jQuery se añadiría el header de la siguiente forma.


$.ajax(
  "https://api.dominio.com/recurso/",
  {"headers": {"API version": "1"}}
);

En cualquier caso, se elija la opción que se elija es importante tener en cuenta que nuestra API puede cambiar en el futuro y facilitar la vida a los desarrolladores que programen los clientes de la misma siempre es una buena práctica.

6 comentarios en “Versiones en nuestra API REST”

  1. El problema de la solución usando una cabecera HTTP es que no se puede usar en JSONP. Si quieres hacer una llamada AJAX desde una web a un API en otro dominio normalmente utilizarás JSONP, que consiste en muy resumidas cuentas en crear un tag , y en tal caso no puedes modificar las cabeceras.

    Saludos!

  2. Yo también opto por la opción de header.

    Aun así, has comentado en ese punto “y si la aplicación cliente tiene las llamadas centralizadas en un único punto no debería ser problema añadir un header extra indicando la versión del API” y esto también es aplicable a tener la versión en la URL. Es más, es raro que el cliente tenga hardcodeada la request URL en el código y no en un fichero config.

    Gracias por tu blog :)

  3. Por cierto, lo más correcto según los puristas de REST sería indicar el número de versión en una cabecera HTTP, pero no una cualquiera, sino en el “Accept” que es estándar. Y usar un mime type propio. Ejemplo: application/vnd.acme.user-v1+xml o application/vnd.acme.user+xml;v=1

    Yo prefiero la versión en la URL por cierto :) Super sencillo de usar y fácil de “enrutar” en un framework web. Aunque no sea tan purista :)

  4. Hola Alberto,

    Debe haber varios puristas por ahí, ya que la mayoría de los que he leído yo aconseja tener la versión en la propia URL.

    El tipo mime me parece una buena idea, pero si añades también metainformación al recurso o quieres asegurarte de que el cliente conozca cómo estructuras la información en el formato que le estás dando y de paso aprovechas para decirle que versión es.

    Yo prefiero mantener las cosas simples y no ser tan estricto con los clientes a menos que use hypermedia o añada metainformación.

    Pero es mi opinión claro ;)

    Un saludo y gracias por tu comentario!

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *