Qué es y cómo crear una API en Ruby on Rails
Lo primero que veremos será que es una API, que conceptos están relacionados a ello y como creamos una en RoR 4 aplicando TDD, junto a algunas gemas que nos ayudarán a hacer nuestro trabajo mas fácil y rápido.
De antemano os aviso que mi meta con éste post no es la de crear un tutorial minucioso sobre como específicamente se debería crear una API si no que le sirva como una introducción al mundo de las API’s ( ◠‿◠).
Luego de trabajar con Ruby on Rails por un corto tiempo, encontré algunos artículos y tutoriales que hablaban sobre que tan fácil era implementar una API con RoR, lo cual me llamo la atención e hizo que investigara más a fondo sobre ello. Curiosamente 1 semana después se me encargo desarrollar una y debo decir que de cierta forma fue una experiencia agradable gracias a la facilidad con que puedes crear grandes cosas en RoR.
Una API es una interfaz de programación de aplicaciones (del inglés API: Application Programming Interface). Es un conjunto de rutinas que provee acceso a funciones de un determinado software.
Como siempre el concepto suena aburrido (ㆆ_ㆆ). Una API nos servirá para que diferentes aplicaciones(web y móviles) puedan comunicarse con nuestra propia aplicación. Que usan estas aplicaciones externas para consumir nuestros servicios? una URL raíz o base que combinada con una serie de ‘end-points’, parámetros o querys, devuelven un conjunto de datos planos-[digo planos porque estos estarán en formatos como xml o json, dejando de lado HTML]-
Como ejemplo tendrías un ‘http://myapiname.com’ como URL raíz y como ‘end-points’ podríamos tener:
http://myapiname.com/users => devuelve la lista de usuarios
http://myapiname.com/users/1 => devuelve un usuario en especifico
http://myapiname.com/users/1/posts => devuelve todos los posts pertenecientes a un usuario en especifico.
La imagen de abajo es un ejemplo perfecto de como los datos serian mostrados si se hace una petición a http://myapiname.com/users -[dentro de los conceptos de una API REST, ‘users’ seria llamado ‘recurso’ que son palabras en sustantivo(no verbos!! 屮ಠ益ಠ屮 ) que se usan para representar a los datos, de por si Ruby on Rails usa esta definición]- XML y JSON son los formatos más usados cuando se trata de API -[recomiendo usar JSON por tener una estructura simple, y al ser un objeto se nos sera mucho mas fácil usar los datos, ademas JSON es mas rápido que XML]-. El formato HTML es usado netamente para desplegar datos en paginas web.
Bye bye front-ends ( ˘︹˘ )…
Para crear una API no necesitaremos hacer uso de CSS o HTML, esto porque simplemente no es necesario. Nuestra API tan solo servirá para que aplicaciones consuman nuestros servicios y lo que estas ‘aplicaciones’ únicamente quieren son lo datos que les interesa, no necesitan que esta data este adornada con HTML o CSS porque, después de todo, serán ellos los que se encargaran de eso.
Una diferencia que pude percibir entre una WEB y una API, es que mientras la primera es diseñada e implementada para ser consumida y usada por usuarios finales, una API es creada para ser usada por desarrolladores y consumida por aplicaciones.
Bien una vez que hemos entendido que es y como funciona una API, veamos como podemos crear una API con RoR 4 -[con la salida de RoR 5 se anuncio que este ya viene con un comando predeterminado para crear API’s]- así que lo primero que haremos es crear un nuevo proyecto llamado my_api.
Para no complicarnos mucho, my_api tendrá un único recurso llamado users, el cual desplegara todos los users en formato JSON.
Creamos nuestra app en RoR con el comando:
$ rails new my_api
Luego nos vamos a la carpeta de nuestro proyecto y configuramos nuestro archivo routes.rb
Según lo de arriba, nuestra URL base o raíz quedara de la siguiente forma:
Si lo notaron, en la linea 5 creé otro namespace-[una namespace nos sirve para agregar un slug ‘/api/’ a nuestra ruta base]- este nos servirá para el versionado de nuestra API. En este caso es ‘v1’ porque obviamente es la primera versión de nuestra API ლ(╹◡╹ლ). Ah! , casi lo olvido, al final de la linea 4 tenemos un format: “json”, con esto le estamos indicando que, por defecto, todos los datos que nos devuelva esa ruta serán en formato JSON.
La URL para acceder a nuestro recurso users, que fue definido en la linea 6, seria la siguiente:
http://localhost:3000/api/v1/users
Bien, ahora vayamos a crear nuestro modelo User, que tendrá únicamente dos campos: name y email
$ rails g model User name:string email:string
Vayamos a agregar unas cuantas validaciones a nuestro modelo para asegurar que los usuarios sean creados correctamente. Pero antes hagamos uso de TDD!! (͡° ͜ʖ ͡°), es decir creemos primero los tests y luego nuestro código-[por cierto si un no has leído el post en donde hablo sobre TDD en RoR lo puedes hacer aquí (͡• ͜ʖ ͡•)]- Para ello usare la famosa gema ‘rspec-rails’ y como complemento a esta usare las gemas ‘shoulda-matchers’, y ‘factory_girl_rails’.
Tenemos 3 tests, los dos primeros sirven para validar que el email y name siempre este presentes en nuestro modelo, y el ultimo para validar que nuestro email sea único, es decir dos usuarios no puedan tener el mismo email ლ(╹◡╹ლ).
Una vez hecha las pruebas, debemos correrlas y obviamente estas fallaran porque aun no tenemos las validaciones en nuestro model ლ(╹◡╹ლ).
Agreguemos las validaciones a nuestro modelo User.
Si corremos los tests estos deberían pasar, así que ahora crearemos nuestros controlador; para ello vamos a nuestra carpeta controller y dentro creamos una carpeta llamada ‘api’ y dentro de esta, otra carpeta llamada ‘v1’ (esto para versionar nuestra API) y finalmente dentro de esta ultima carpeta crearemos nuestro controlador llamado ‘users_controller.rb’. PERO ANTES!! crearemos los tests (͡° ͜ʖ ͡°), ya saben lo que dicen: test first (͡° ͜ʖ ͡°).
Estos serán nuestros tests para nuestro controlador que únicamente tendrá un método para obtener todos los datos en formato JSON. Dentro de nuestra carpeta ‘spec’ crearemos una carpeta llamada ‘requests’ -[el nombre hace referencia a que testearemos nuestras peticiones o requests de nuestra API]- y dentro nuestro archivo llamado ‘user_spec.rb’.
Y aunque lo parezca, el test de arriba es muy sencillo. Tenemos un describe(linea 7) que nos servirá para agrupar nuestra petición GET con la que obtendremos todos los usuarios. Luego de esto tenemos un before , que tiene un grupo de lineas de código que se ejecutaran antes de cada prueba, aquí creamos un usuario haciendo uso de las funcionalidades de la gema FactoryGirl -[en este caso estamos creando una lista con create_list, este acepta dos parámetros: el primero sera nuestro nombre del modelo a crear y el segundo el numero de registros que se crearan]- la linea 10 la agregamos para que antes de cada prueba mande una petición GET a “http:localhost:3000/api/v1/users”.
Nuestro primer test (linea 13) sirve para comprobar que el status de la petición sea de 200 ( es decir que todo resulto como queremos, sin errores), y el segundo (linea 14) es para comprobar que la petición nos devolvió un JSON con la misma cantidad de objetos que hay en nuestro modelo User.
Ahora agreguemos código a nuestro controlador:
El código no es nada de otro mundo, tenemos una variable global @users a la cual le asignamos todos los registros que hay en nuestro modelo User.
Y finalmente nuestra vista tendrá lo siguiente:
Notaras que nuestra vista esta dentro de la carpeta /views/api/v1/users, que es una estructura similar a la de nuestro controlador. El formato de nuestra vista sera ‘json.jbuilder’ , esto nos permitirá desplegar datos en formato JSON ლ(╹◡╹ლ). La sintaxis usada tampoco es nada complicada, iteramos todos los objetos que tiene nuestra variable @users, y le especificamos cuales son los campos que queremos mostrar.
Finalmente si agregamos un par de registros a nuestro modelo User, y accedemos a http://localhost3000/api/v1/users tendremos lo siguiente:
Finally…We did it!! (҂◡̀_◡́)ᕤ …
Ruby on Rails nos permite crear cosas fabulosas de forma muy rápida, realizando el mínimo esfuerzo posible.
Aun hay muchos conceptos por aprender dentro de las API’s, pero decidí pasar de ellos por no hacer el post mas largo de lo que ya es. Espero que esto le haya sido de ayuda y le sirva, como lo mencione al inicio, como una introducción al mundo de las API’s.
Gracias por leer..! (ಥ_ಥ)
Pueden revisar otros posts (҂◡̀_◡́)ᕤ
Por cierto, aquí le dejo los links de las gemas usadas en el post junto a la documentación oficial de Ruby on Rails sobre API’s.
