Primera API REST en Node JS y Express

Después de contaros cómo instalar Node JS, es hora de ponerse a programar. Os vamos a explicar cómo crear una API REST en Node JS. Como ya sabemos, Node JS está basado en JavaScript por lo que necesitaremos ciertos conocimientos básicos de Java (o de JavaScript) para seguir bien este artículo.

Framework

Para el desarrollo de esta primera API REST en Node JS vamos a utilizar su framework más conocido y extendido: Express. Este framework ofrece una multitud de herramientas que nos facilitan enormemente la implementación. Además necesitaremos otro paquete para poder parsear los mensajes que recibamos en la API, para ello usaremos body-parser.

Cabe destacar que este ejemplo lo haremos “a lo bruto”, contaremos cómo se haría de forma muy básica la API utilizando parte de lo que nos ofrece express. No ahondaremos en cómo debe estructurarse un proyecto de este tipo, eso lo dejamos para otro artículo.

Y concluidas las presentaciones… ¡al lío!

Preparación del entorno

Teniendo ya instalado Node, vamos a necesitar crear un proyecto nuevo. Como ya comentamos en el artículo de instalación, nosotros utilizaremos el editor de texto Atom para el desarrollo de aplicaciones Node JS.

Para la creación del proyecto solo tendremos que crear una nueva carpeta en el directorio que deseemos, en nuestro caso primera_api_node, y abrir esa carpeta desde Atom pulsando File> Open folder… y seleccionando dicha carpeta.

Lo primero que haremos aquí será crear un fichero JavaScript, pulsando botón derecho sobre la raíz del proyecto y New File. Este será el fichero .js donde escribiremos el código de nuestra API, más adelante.

Hecho esto solo tendremos que habilitar el autocompletado para este proyecto pulsando sobre la pestaña Packages > Atom Ternjs > Configure project. Esto generará el fichero .tern-project.

Tras estos pasos el proyecto tendrá este aspecto:

Llegados a este punto tendremos que instalar los paquetes que vamos a necesitar para el desarrollo. Como ya os imagináis, usaremos npm para este cometido. Tras situarnos en la carpeta del proyecto a través de un terminal, ejecutaremos el siguiente comando:

npm install express body-parser

Esto nos habrá generado una carpeta dentro de nuestro proyecto con el nombre node_modules que contiene los paquetes que acabamos de instalar. Además se habrá generado un fichero package-lock.json que contiene información sobre éstos, como versiones, dependencias, etcétera.

¡Con esto ya tenemos todo listo para empezar a hacer nuestra API!

Código de la API

Vamos a ir haciendo el desarrollo por partes, de lo más general a lo más específico. Además vamos a hacerlo de forma que podamos ir ejecutando a cada cambio que incluyamos, de esta manera vamos viendo más fácilmente qué hacemos.

1. Definición de constantes e importaciones

Lo primero que debemos hacer es importar las librerías que hemos instalado previamente. Para ello usaremos «require» que buscará en el directorio node_modules las dependencias. En caso de no encontrarlas las busca tomando como raíz el proyecto, esto es útil si queremos usar nuestros propios ficheros JavaScript definidos en el proyecto.

Además necesitaremos inicializar la API mediante la funcionalidad que nos ofrece Express y le indicaremos que utilice body-parser como método de parseo de las request.

Finalmente vamos a crear una constante para indicar el puerto que escuchará nuestra API y a través de la variable API que hemos creado indicaremos al servidor que comience a escuchar ese puerto.

Esta sería la primera parte del desarrollo donde tendremos todo definido y listo para escribir los métodos de nuestra API. En este punto ya podemos ejecutar el servidor. Si como nosotros, utilizais Atom, pulsando Ctrl + R arrancaremos el servidor. Esto levantará una instancia del servidor indicando que está listo para atender peticiones en el puerto 8080, como muestra el mensaje en la consola.

En este momento podremos hacer llamadas desde el navegador u otro cliente a la URI http://localhost:8080.

Como aún no hemos definido ningún método para nuestra API obtendremos el error que mostramos en la imagen, pero esto ya nos sirve para saber que nuestro servidor está arrancado correctamente.

2. Creación de operaciones para la API

No vamos a hacer el típico Hello world, sería demasiado sencillo e insuficiente para lo que queremos mostrar. Para este ejemplo vamos a hacer una API que nos permita gestionar nuestras notas, necesitaremos los cuatro típicos métodos REST: GET, POST, PUT y DELETE. No nos centraremos ahora en cómo o dónde almacenar información, así que hemos creado un mapa como “sistema” de almacenamiento.

Con Express lo único que tendremos que hacer es indicar que esperamos un método REST de la siguiente manera:

Podemos ver que utilizando la variable api podemos usar el método get, donde definimos la URI como primer parámetro y después indicamos los dos parámetros que recibe la función que implementaremos a continuación. Estos dos parámetros son siempre req y res, hacen referencia y nos permiten interactuar con la petición (request) y la respuesta (response). Puede incluirse un tercer parámetro llamado next que será una función que queramos que se ejecute después del código que hemos definido, por ahora la obviamos.

3. Método GET

Pasando a la definición del comportamiento del método GET podemos ver cómo se hace uso del envío de la respuesta. Haremos uso de la variable res, que identifica la respuesta. Esta variable tiene métodos que nos permiten enviar información al cliente como se ve a continuación:

El método getNotas() simplemente devuelve un array de objetos que tienen una nota y un id de nota. Si te interesa ver la implementación completa dejamos todo el código subido a GitHub.

Podemos ver que a través de la variable res usamos el método send que se encarga de convertir a JSON la respuesta y enviarla al cliente. Por defecto se transmite al cliente un estado http 200, salvo que se especifique lo contrario como veremos a continuación.

4. Método POST

Para crear notas usaremos el método POST, en el cual necesitaremos validar que la petición contiene los datos necesarios para guardar en nuestro sistema. Por ello necesitaremos validar que la request contiene el campo nota. En caso de que no sea válido devolveremos una respuesta de error, de lo contrario guardaremos la nota y responderemos que todo ha ido correctamente.

Aquí podemos ver varias funcionalidades que nos ofrece Express. Por un lado vemos cómo acceder al contenido de la request a través de la variable res que hace referencia a la petición. Obtenemos el valor nota de la variable req como si fuera un objeto haciendo uso del punto y accediendo a body, donde viene el cuerpo de la request.

Además vemos que en el caso de que no se introduzca una nota en la petición devolvemos un error donde indicamos el código http de error 400, haciendo uso de la variable res y el método status que recibe como parámetro el estado a devolver.

Cabe destacar que como respuesta devolvemos unos mensajes que hemos definido como constantes previamente.

5. Método PUT

Para la actualización de elementos usaremos el método PUT. En este caso recibiremos en el cuerpo de la petición la información que actualizaremos y además recibiremos como parámetro en la URI el identificador de la nota que vamos a actualizar. Al igual que antes necesitaremos validar la request, además en este caso verificamos que recibimos un identificador que existe en nuestro sistema de almacenamiento.

En este caso podemos observar de qué manera definimos un parámetro que debe ser introducido en la URI, el id. Para ello en el primer parámetro del método put indicamos :id para especificar que la URI tiene un parámetro y lo llamamos id.

Vemos también cómo acceder a este parámetro, haciendo uso del mismo objeto req y accediendo a params seguido del campo que buscamos.

Junto a los mensajes anteriores, hemos definido también un mensaje estándar para el error de nota no encontrada:

6. Método DELETE

Usaremos el método DELETE para el borrado de elementos de nuestro sistema. Al igual que en el PUT validaremos que la nota que vamos a borrar se encuentra en el sistema.

Comprobación del funcionamiento

Llegados a este punto podemos ejecutar la API REST en Node JS que acabamos de desarrollar teniendo ya su funcionalidad completa. Antes de nada debemos arrancar el servidor con la API.

Nuestra recomendación es que para probar esta API o cualquier otra uséis Postman. Es una herramienta muy completa y muy útil para hacer peticiones a APIs y ver sus resultados. Si aún no lo conocéis pasaros por aquí para ver cómo usarlo.

Probaremos primero el método POST donde crearemos dos notas con los siguientes mensajes:

Ambas notas han sido insertadas correctamente, como podemos ver en las respuestas. Pero nos cercioramos de esto haciendo uso del método GET.

Vemos que se encuentran las dos notas que hemos insertado previamente, además vemos los identificadores de cada nota, muy útil para nuestras próximas pruebas.

Seguiremos con la actualización. Haremos una petición para actualizar la nota con identificador 0 y verificaremos que se ha actualizado haciendo utilizando el método GET.

Por último probaremos el borrado de elementos. Eliminaremos la nota con identificador 1 y comprobaremos con GET que solo tendremos una nota en el sistema.

Podríamos incluir otras pruebas donde verifiquemos las validaciones y mensajes de error que hemos definido, pero eso os lo dejamos a vosotros ;-). Os dejamos en este enlace la colección de pruebas en Postman para que solo tengáis que importar y hacer pruebas, ¡más fácil imposible!

Conclusiones

En este artículo hemos visto cómo crear nuestra primera API REST en Node JS haciendo uso del Framework más usado para este cometido. Como os habréis dado cuenta es sumamente sencillo, conociendo cuatro conceptos podremos hacer nuestros propios desarrollos. Para que os sea más fácil aún hemos dejado el código subido a GitHub por si queréis revisar el código completo.

Esto es solo la primera API, lo que quiere decir que hay muchos aspectos mejorables que abordamos en otros artículos.

Esperamos que os haya sido de utilidad y como siempre, os animamos a que hagáis vuestras propias pruebas y si tenéis cualquier problema contactad y expongais vuestras dudas, sugerencias o peticiones.