Es la tercera vez que me cruzo en internet (y fuera de internet) con el dilema del versionado de APIs: ¿cómo o dónde especificar la versión?. Los pragmáticos apuestan por la URL, los RESTafaris por un header. ¿Pero cuales son las ventajas e inconvenientes de cada método?
Uso de cabeceras HTTP
Mi estrategia habitual es hacer las cosas siempre de la forma más ortodoxa y elegante posible. A veces las restricciones no funcionales nos obligan a tomar «atajos» y dejar los buenos modales de lado. El resultado puede ser una solución no tan bonita a ojos de expertos desarrolladores, pero que de cara al gran público es una maravilla porque hace lo que tiene que hacer. En el caso de los APIs, el consumidor es un desarrollador, así que la solución sea bonita implica que sea elegante y ajustada a la ortodoxia.
Dicho esto, podríamos decir que el lugar lógico u ortodoxo para identificar la versión de un API debiera ser la cabecera HTTP. Las cabeceras HTTP están concebidas para ubicar metadatos acerca de los datos intercambiados en el cuerpo de la petición y en las respuestas. La versión del API es un metadato, ¿no?.
Por ejemplo nosotros podríamos usar la siguiente cabecera:
X-Byteflair-APIVersion: 1
Uso de la URL
El uso de cabeceras funciona genial en comunicaciones máquina a máquina (M2M) o cuando una aplicación web utiliza el API desde su backend. Pero si tu cliente es un navegador y el API de un tercero necesitas atacarlo con peticiones AJAX, estás perdido… al menos durante los próximos meses/años.
El problema es que hasta ahora, la única forma de hacer peticiones HTTP desde un navegador a un API usando código JavaScript con un origen distinto del servidor del API, era a través de JSONP. Este método funciona insertando de forma dinámica un elemento script como base para realizar la petición HTTP (si quieres saber más, la wikipedia lo explica fenomenal). Por lo tanto, es imposible modificar las cabeceras HTTP, y además, sólo se puede hacer GET.
En este caso, el único lugar donde podemos incluir la versión es la URL o el Query String, y de los dos, el más apto es la URL.
https://api.byteflair.com/v1/...
CORS ha venido a salvarnos y redimirnos de JSONP. CORS o Cross Origin Resource Sharing (de nuevo, si necesitas profundizar más la wikipedia es un buen comienzo), es una tecnología que permite compartir recursos de distintos orígenes sobre el navegador. El problema de CORS es que no sólo debe ser soportado por el proveedor del API, sino también por el navegador de los usuarios de aquellos que desarrollan aplicaciones web sobre tu API. Y hasta que eso ocurra va a pasar un tiempo, diría que unos meses, quizás un año.
JSONP necesita ser soportado por el proveedor del API. Pero funciona en todos los navegadores. Por eso hasta que CORS sea de adopción masiva parece que hay que seguir pecando con JSONP.
Conclusiones
Si desarrollas APIs, el uso de la cabecera para versionar las releases esta muy bien. Pero tendrás que tener en cuenta quién va a usar tu API, con que fin y desde que clientes. Si un modelo de uso va a ser el invocar tu API directamente desde el navegador a través de peticiones AJAX, tendrás que decidir ir por CORS o JSONP. Sólo en caso de optar por dar soporte a JSONP, estarás obligado a cambiar tu estrategia de versionado: ¿quizás usar la url?.
Y tú, ¿Qué decisiones has tomado en cuanto al versionado de tus APIs? ¿cuales han sido las razones? ¿Qué otras ventajas e inconvenientes ves a estos métodos?
Weblografía
Poco después de publicar este artículo encontré este otro post de Programmable Web en el que enumeran distintas técnicas de versionado. A pesar de que no entra en profundidad en ninguna de ellas puede ser de utilidad.