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.
\nSi 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.
\nLa 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.
\nLas opciones más habituales para hacer esto serían:
\nhttps://api.dominio.com/v1/recurso/
\nEste sería un ejemplo de URL en la que se indica la versión de la API en la misma.
\nEsta 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.
\nhttps://api.dominio.com/recurso/?v=1
\nEste tipo de opción se usa por ejemplo en la API de YouTube.
\nYo 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.
\n**https://api.dominio.com/recurso/ **\n“API version”: 1
\nEsta 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.
\nDespué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.
\nEn javascript por ejemplo tendríamos el siguiente código para añadir un header http a nuestra llamada AJAX.
\n\nvar request = new XMLHttpRequest();\nrequest.open("GET", "https://api.dominio.com/recurso/", false);\nrequest.setRequestHeader("API version", "1");\nrequest.send();\nEn jQuery se añadiría el header de la siguiente forma.
\n\n$.ajax(\n "https://api.dominio.com/recurso/",\n {"headers": {"API version": "1"}}\n);\nEn 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.
" newsletter: "Asier Marqués, blog personal" newsletter_handle: "blog-asiermarques-com" newsletter_url: "https://usecommune.com/n/blog-asiermarques-com" author: "Asier Marqués (@asier)" published: "2012-12-04T14:57:51.000Z" canonical_url: "https://usecommune.com/n/blog-asiermarques-com/a/versiones-en-nuestra-api-rest" markdown_url: "https://usecommune.com/n/blog-asiermarques-com/a/versiones-en-nuestra-api-rest.md" chat_url: "https://usecommune.com/n/blog-asiermarques-com/a/versiones-en-nuestra-api-rest/chat" source_url: "https://blog.asiermarques.com/2012/versiones-en-nuestra-api-rest/" body_source: "imported" likes: 0 replies: 0 body_words: 412 --- # 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:\
\\\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.\
\\\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.\
\\*\*\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.\
*** ## Discussion No replies yet.