Este 2016 desde el inLab hemos desarrollado una nueva API para la FIB. El objetivo del proyecto era dar, de forma estructurada, la información publica de la FIB. Como da más información que la anterior versión, hemos decidido que era hora de desvincularla del "Racó" y darle la importancia que se merece. Os presentamos pues la nueva versión de la API:
Hay que añadir que la versión anterior de la API del "Racó" seguirá en funcionamiento y en mantenimiento, todo y que ahora los esfuerzos se concentrarán en facilitar el acceso de recursos vía la nueva versión.
Como hemos diseñado esta API?
La versión anterior de la API se creó a medida para las aplicaciones móviles y por la integración de servicios dentro de la FIB. Su arquitectura pues, era muy poco homogénea. La API estaba formada por servicios creados ad-hoc, sin un formato común y que sólo estaban bajo un mismo paraguas para facilitar su uso. Sin embargo, han cumplido su objetivo durante mucho tiempo.
Empezar una nueva versión desde cero nos dio la oportunidad para crear una estructura común a seguir. En este caso nos dejamos guiar por la filosofía REST. La nueva versión de la API está compuesta por un conjunto de recursos enlazados entre sí. Los enlaces permiten que sea auto explorable sólo obteniendo la página inicial. Esto facilita la posibilidad de hacer la API auto-documentada: las mismas URLs de los recursos tienen la documentación para su propio uso. Por otra parte, otra característica de la API es que los recursos se pueden obtener en diferentes formatos. De forma genérica se puede obtener en json y la documentación en formato de página web. De forma más específica, podemos encontrar como recursos internos se pueden obtener también en formato iCalendar, JPEG o PNG. (1)
Internamente se ha utilizado el framework Django REST Framework para desarrollarla. Sobre este framework hicimos artículo en este mismo blog (http://inlab.fib.upc.edu/es/blog/django-api-rest). El uso de este framework nos facilita muchísimo que el diseño de la API sea coherente y también que sea autodocumentada.
Actualmente, la API es únicamente de lectura. Se ofrecen los datos de diferentes sistemas de la FIB de una forma unificada: datos de gestión académica, sistema de reservas de aulas, sistema de reservas de salas de presentaciones, ocupación de los PC … Muchos de estos sistemas comparten una misma base de datos.Con el fin de ayudar en la estructuración de los datos se ha hecho unas vistas SQL que exponen la información que nos interesa ofrecer y aplica transformaciones si es necesario. Por otra parte, algunos servicios han requerido otros métodos para obtener los datos. Algunos son basados en llamadas http a otros servicios internos. En resumen pues, la nueva API hace de fachada de todos los sistemas de la FIB. Aislando así las complejidades internas de cómo están estructuradas los datos.
API pública vs API privada
Mucha de la información que proporciona la API es totalmente pública. De hecho, en paralelo a la creación de la API se ha estado trabajando para que la web de la FIB obtenga toda la información vía API. Así pues la información abierta en la web de la FIB como listas de asignaturas, horarios, la guía docente, las universidades con las que hay programas de intercambio …ahora es también consultable vía la nueva API. Para acceder a esta información, necesitará un client_id que podrá pedir utilizando su login del "Racó".
Por otro lado, tenemos una parte privada de la API que muestra información personalizada de los estudiantes del "Racó". Para proteger esta parte, decidimos seguir el protocolo de autorización OAuth 2.0.
Hace ya unos 4 años os enseñamos cómo utilizar OAuth 1.0 a la API del "Racó". Pues bien, ahora os enseñaremos cómo utilizar la segunda versión de este protocolo.
OAuth2
Tenemos una aplicación de ejemplo en:
https://github.com/FIBUPC/demo_fib_api_flask
Que podemos ver en funcionamiento en:
http://demo-api-fib-oauth.herokuapp.com
Puede probarlo en una app aparte de heroku usando el botón de "Deploy to Heroku" en el repositorio o siguiendo el siguiente enlace:
https://www.heroku.com/deploy?template=https://github.com/FIBUPC/demo_fib_api_flask/tree/master
OAuth 2.0 permite diferentes flujos de autenticación. La API sólo tiene implementado el Authorization code, para aplicaciones en el servidor que es el que utiliza esta aplicación. El flujo es el siguiente:
Si nosotros como programadores estamos interesados en hacer una aplicación que utilice la API privada, lo que tendremos que hacer primero es darla de alta en la API y obtener un client_key y un client_secret. Estos dos valores identifican nuestra aplicación a la API. Es importante no compartirlos, especialmente el client_secret, ya que es como la contraseña de nuestra aplicación.
El botón de login de la aplicación apunta a una pantalla de la API donde se nos pide la autorización para la aplicación. Previamente a ver esta pantalla, el usuario habrá hecho login en la API y por tanto como usuario estamos autorizando a la aplicación acceder a nuestros datos
Una vez el usuario ha aceptado, la API redirigirá hacia la URL que hemos indicado al registrar la aplicación, que recibirá un parámetro llamado "authentication code".
A partir de este "authentication code", la aplicación pide a la API un token. Este token queda vinculado al usuario que ha entrado a la aplicación y permite acceder a la API en su nombre durante un período limitado de unas 6 horas. (2)
Gracias al que el usuario está autenticando y está dando confirmación directamente a la API, la aplicación no tendrá nunca las credenciales y por tanto no pueden quedar comprometidas.
Todo esto que parece tan complicado queda escondido por las librerías de OAuth. En la aplicación de ejemplo, simplemente debemos pasar las credenciales de la aplicación, la URL donde el usuario debe hacer login y la URL de autorización. La librería se encarga del resto, añadiendo a las peticiones a la API las cabeceras pertinentes con los toquens.
Una aplicación de móvil también puede utilizar este flujo, aunque el client_secret está en manos del cliente y no en un servidor al que el usuario no tiene acceso. Es importante que a pesar de ser una aplicación nativa, la autorización de la aplicación se haga en un navegador y no una webview interna para asegurar que la aplicación no tiene ningún acceso a las credenciales. Pero de todo esto … tal vez habría que hacer otro artículo entero. (3)
Para qué puede servir la API?
El hecho de disponer de una API pública permite que no sólo el inLab pueda crear nuevas aplicaciones útiles para la comunidad de la FIB. El acceso controlado a los datos permite que cualquier estudiante o profesor pueda convertirse en desarrollador. Y talento y ganas en esta facultad precisamente no faltan.
Por ejemplo, gracias a la API se podría hacer …
Un explorador de horarios dinámico durante la matrícula que tenga en cuenta qué grupos están llenos o a punto de llenarse.
Un clásico que todo fiber ha pensado alguna vez: un programa para generar horarios sin "solapamientos". Y con un extra: hacer que los exámenes finales queden lo más espaciados posibles.
Una app que nos diga a qué aula tenemos que ir si queremos tener un PC durante 3 horas sin interrupciones. Y que nos avise de cuando tenemos clase!
Soy un profesor y necesito 4 aulas de laboratorio durante 2 horas para hacer un examen. Tengo algún espacio disponible?
Pintar un grafo de los requisitos para ver qué asignaturas se deben hacer para hacer una concreta.
Un planificador de viajes en función de los días festivos del cuatrimestre correspondiente.
Estos no son más que ejemplos que me pasan por la cabeza ahora mismo. Seguro que vosotros tendréis de mejores. Esta es la razón por la que hemos hecho la nueva API!
Futuro de la API
Uno de los primeros objetivos a la hora de diseñar la nueva API era que se pudiera continuar su desarrollo una vez lanzada. La idea es continuar haciendo crecer la API con el tiempo poniendo a disposición pública nuevos datos. En este sentido, estamos abiertos a sugerencias! ¿Le gustaría ver algúna información en específico a la API? Escríbanos un ticket y lo estudiaremos.
Creemos que la nueva API puede ser una oportunidad excelente para crear comunidad en la FIB. Es por ello que también os animamos a decirnos que pensáis, como la estais utilizando, compartir vuestras aplicaciones.
Referencias
https://api.fib.upc.edu/v2/docs/main – Documentación con formatos de la API
http://stackoverflow.com/questions/17427707/whats-the-right-oauth-2-0-flow-for-a-mobile-app/38582630#38582630 – En apps web … no hacer una webview. El login debe ser en un navegador independiente para asegurar que la aplicación no puede acceder a los passwords!
https://api.fib.upc.edu/v2/docs/oauth -Documentación detallada OAuth de la API
Bibliografía recomendada OAuth
http://stackoverflow.com/a/32534239/7020590 – OAuth 2.0 Donuts, probablemente una de las mejores explicaciones del funcionamiento de OAuth para aquellos que apenas están empezando a trabajar con APIs y protocolos de autorización.
https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2 – Un buen tutorial de cómo funciona OAuth 2.0. El tutorial de nuestra API está basado en este.
https://tools.ietf.org/html/rfc6749 – Publicación oficial del protocolo OAuth 2.0.