Tabla de contenido

Portada
Introducción 1.1
¿Que es un API? 1.2

Configurando el proyecto con Express JS

Inicializando el proyecto 2.1
Herramientas de desarrollo 2.2
Crear un simple Web Server 2.3
Utilizando Express JS 2.4
Configuración y variables de entorno 2.5
Middleware para manejo de errores 2.6
Sistema de Logs 2.7
Postman 2.8

Router y Routes en Express JS

Utilizando el Router y Routes de Express 3.1
Creando el layout del API 3.2
Capturando y procesando parámetros de las peticiones 3.3

Patrones asincrónicos de JavaScript

Patrones asincrónicos de JavaScript 4.1
Callbacks 4.2
Promises 4.3
async / await 4.4

Persistencia de datos

2
Bases de datos SQL y NoSQL 5.1
Instalando y configurando MongoDB 5.2
Conectando con MongoDB 5.3
Mongoose Models 5.4
Procesando parámetros comunes con middleware 5.5
Estandarización de la respuesta 5.6
Mongoose Schemas 5.7
Paginación 5.8
Ordenamiento 5.9
Creando recursos 5.10
Relaciones entre recursos 5.11
Consultar recursos anidados 5.12
Añadir recursos anidados 5.13

Asegurando el API
Añadir y remover campos de un documento 6.1
Administración de usuarios 6.2
Autenticación de usuarios 6.3
Autorización de usuarios 6.4
Validaciones personalizadas 6.5
Limpieza de campos 6.6
Restricción de las peticiones 6.7

Probando el API
Pruebas 7.1
Configurando pruebas 7.2
Pruebas unitarias 7.3
Pruebas de integración 7.4

Documentando el API
Configurando Swagger y JSDoc 8.1

3
Documentando las rutas y creando modelos 8.2
Conclusión 8.3

4
Introducción

Introducción

A quién está dirigido este libro

Este libro va dirigido a programadores que han iniciado con Node.js o tienen experiencia en
otros lenguajes de Backend como Java, Rails o PHP y quieren utilizar Node.js como
componente de Middleware o Backend para hacer un REST API Web.

Si eres nuevo en Javascript se recomienda tomar el siguiente curso:

Introduction to JavaScript - Code Academy

Adicionalmente en este libro se asume conocimientos de los features básicos de ES2015 al

menos:

Arrow functions
let + const
Template Strings
Destructuring assignment
Promises

Para mayor información puede consultar el siguiente enlace:

Learn ES2015 - Babel

Si eres nuevo en Node.js se recomienda leer el siguiente libro de este misma serie:

Introducción a Node JS

También se asume que el lector tiene conocimientos básicos de comandos en la Terminal y

utilización básica de git.

Acerca de este libro

Este libro tiene un objetivo teórico-práctico, durante el transcurso de este construiremos una
aplicación desde el inicio hasta el fin, comenzaremos por lo conceptos básicos y
gradualmente en cada capítulo introduciremos nuevos conceptos, fragmentos de código y
buenas prácticas, veremos como la aplicación se convierta en un proyecto robusto. Pero a
su vez si usted lo desea puede saltar a un capitulo en especifico, por ejemplo para ver el
versionamiento de API o la persistencia de datos con MongoDB.

5
Introducción

Utilizaremos git como software de control de versiones para organizar cada uno de los
pasos incrementales (features) de la aplicación, brindando así la posibilidad de saltar a un
paso específico en el tiempo de desarrollo del proyecto y si usted lo desea comenzar desde
allí, a la vez nos brinda la ventaja de ver los cambios en los archivos de manera visual y así
poder comprobar en caso de una omisión o error.

Acerca del autor

Soy un entusiasta de la Web desde la década de finales de los 90 cuando se utilizaba el
bloc de notas y nombre de etiquetas en mayúsculas para hacer las páginas Web, soy
Ingeniero de Sistemas y tengo más de diez años de experiencia como profesor de pregrado
en la asignatura de programación bajo la Web y en posgrado con otras asignaturas
relacionadas con el mundo de desarrollo de software, trabajo actualmente en la industria del
desarrollo de software específicamente la programación Web. Puedes encontrar más
información acerca de mi hoja de vida en el siguiente enlace: http://gmoralesc.me.

Gustavo Morales

Agradecimientos
Quiero agradecer a mi esposa Milagro y mi hijo Miguel Angel por apoyarme y entender la
gran cantidad de horas invertidas frente al computador: investigando, estudiando, probando
y escribiendo.

6
¿Que es un API?

¿Que es un API?
Es un acrónimo en inglés de Application Programming Interface, lo cual en otras palabras
un pocos menos abstractas, es la interfaz que una aplicación expone para que otras
aplicaciones interactúen con sus métodos o servicios, a través de una interfaz
consumiendo unas recursos específicos.

API Web
En nuestro proyecto crearemos una API Web la cual utiliza como interfaz el protocolo Web
es cuál es HTTP (o HTTPS sea el caso) y los recursos son las entidades, por ejemplo
nosotros vamos a crear un administrador de tareas por lo tanto nuestros recursos serán
tareas, usuarios y grupos, entonces nuestras entidades serán: tasks, users y groups,
normalmente las entidades se nombran el plural y las cuales se acceden a través de unas
rutas en este caso son urls.

Se recomienda utilizar el idioma inglés independientemente de la lengua nativa de la

aplicación.

Existen otros tipos de API por ejemplo en vez del protocolo HTTP pueden ser sockets y en
vez de entidades pueden ser canales, este tipo de API son muy utilizadas en juegos en
línea, por lo tanto es importante definir que tipo de API estamos construyendo.

Códigos y verbos HTTP

El protocolo HTTP utiliza diferentes verbos para las diferentes operaciones que se realizan
y dependiendo el resultado de estas operaciones vienen con diferentes códigos.

Los verbos más utilizados por defecto en la Web son:

GET: Se utiliza cuando se envía una solicitud para obtener un recurso por ejemplo un
documento HTML a través de una url.
OPTIONS: Se utiliza como petición auxiliar para comprobar si el servidor soporta el
método que se va a utilizar en general cualquiera diferente a GET, esta comprobación
se llama preflight.
POST: Se utiliza para crear un recurso, normalmente enviar información de formularios
Web.

Pero no son los únicos, existen además: PUT, PATCH y DELETE.

7
¿Que es un API?

Dentro del listado de códigos tenemos:

2xx: Este grupo se utiliza para operaciones exitosas.

200: Cuando la operación es exitosa.
201: Lo mismo que el 200 pero en este caso cuando además se crea un recurso
de manera exitosa.
204: Lo mismo que el 201 pero esta vez no fue necesario enviar ningún tipo de
información de vuelta
3xx: Este grupo se utiliza para indicar redirecciones.
4xx: Este grupo se utiliza para enumerar los errores del lado del cliente.
400: Indica que la petición no fue bien realiza normalmente cuando los datos se
envian mal formados.
401: No está autorizado para acceder al recurso, normalmente se utiliza cuando no
se está autenticado.
403: Puede que esté "autenticado" pero no tiene permisos para acceder a ese
recurso
404: Recurso no encontrado
422: Indica que la petición no se puede procesar debido a que faltan datos
requeridos o están en un formato incorrecto.
5xx: Este conjunto asociado a errores del lado del servidor.

REST API Web

REST es un acrónimo de Representational State Transfer, que especifica un contrato por
defecto para la relación que debe haber entre las rutas, verbos, códigos (estos dos
anteriores pertenecientes al protocolo HTTP) y operaciones principales como: Crear
(Create), Leer (Read), Actualizar (Update) y Borrar (Delete) conocido mucho por su
acrónimo CRUD, la siguiente tabla mostrará cómo sería para nuestra entidad tasks:

Status
Verbo Operación Descripción
Code
/api/tasks/ POST 201 CREATE Crear un tarea

/api/tasks/ GET 200 READ Leer todos las tareas

/api/tasks/:id GET 200 READ Leer una tarea

PUT / Actualizar la información de

/api/tasks/:id 200 UPDATE
PATCH una tarea
200 (o
/api/tasks/:id DELETE DELETE Eliminar una tarea
204)

8
¿Que es un API?

Este contrato no es una camisa de fuerza, pero se deben respetar las definiciones básicas,
no está permitido por ejemplo crear una tarea con el método DELETE en vez de POST, no
tiene mucho sentido, pero se pueden añadir más muchas más operaciones, recursos
anidados y demás, se dice que un API es RESTful cuando cumple con este contrato
mínimo.

9
Inicializando el proyecto

Inicialización del proyecto

Seleccionamos un directorio de trabajo y creamos el directorio de la aplicación:

mkdir checklist-api && cd checklist-api

Inicializamos el proyecto de Node JS:

npm init -y

El comando anterior genera el archivo package.json que luego se puede editar para
cambiar los valores de la descripción, autor y demás.

Inicializamos el repositorio de git:

git init

Creamos el archivo .gitignore en la raíz del proyecto:

touch .gitignore

Con el siguiente contenido y lo guardamos:

node_modules/
.DS_Store
Thumbs.db

Creamos el archivo principal de la aplicación:

touch index.js

Agregamos el script inicial en el archivo package.json para ejecutar nuestro archivo

principal:

"scripts": {
"start": "node index",
"test": "echo \"Error: no test specified\" && exit 1"
},

10
Inicializando el proyecto

Para terminar con la configuración de la aplicación hacemos el commit inicial:

git add --all

git commit -m "Initial commit"

11
Herramientas de desarrollo

Herramientas de desarrollo

Nodemon
Es muy tedioso cada vez que realizamos un cambio en los archivos tener que detener e
iniciar nuevamente la aplicación, para esto vamos a utilizar una librería llamada nodemon,
esta vez como una dependencia solo para desarrollo, ya que no la necesitamos cuando la
aplicación esté corriendo en producción, esta librería nos brinda la opción de que después
de guardar cualquier archivo en el directorio de trabajo, nuestra aplicación se vuelva a
reiniciar automáticamente.

npm install -D nodemon

Luego modificamos la sección de scripts del archivo package.json para añadir el script
que ejecutará nuestra aplicación en modo de desarrollo y en el script start en modo de
producción, de la siguiente manera:

"scripts": {
"dev": "nodemon",
"start": "node index",
"test": "echo \"Error: no test specified\" && exit 1"
},

No es necesario indicarle a nodemon que archivo va a ejecutar pues por convención

buscará el archivo index.js , el cual es el punto de entrada de nuestra aplicación. Mas
adelante se configurará el script de pruebas: test

Si el servidor se está ejecutando lo detenemos con CTRL+C , pero esta vez lo ejecutamos
con npm run dev .

Para comprobar que todo esté funcionando, abrimos el navegador en la siguiente dirección
http://localhost:3000 .

Antes de finalizar hacemos commit de nuestro trabajo:

git add --all

git commit -m "Add Nodemon for development"

Más información:

12
Herramientas de desarrollo

Nodemon

ESLint
Es recomendado añadir una herramienta que nos compruebe la sintaxis de los archivos
para evitar posibles errores y porque no, normalizar la forma en que escribimos el código,
para ello utilizaremos una librería llamada ESLint que junto con el editor de texto
comprobará la sintaxis de los archivos en tiempo real:

npm install -D eslint

ESLint nos permite seleccionar una guia de estilo ya existente o también poder crear
nuestra propia guia, todo depende del común acuerdo del equipo de desarrollo.

Inicializamos la configuración con el siguiente comando:

./node_modules/.bin/eslint --init

Alternativamente con la utilidad npx , instalada globalmente por Node.js, con el siguiente
comando:

npx eslint --init

Si ESLint está instalado de manera global, el comando anterior se podría reemplazar

con: eslint --init

Contestamos las preguntas del asistente de configuración de la siguiente manera:

? How would you like to use ESLint?

To check syntax only
To check syntax and find problems
❯ To check syntax, find problems, and enforce code style

? What type of modules does your project use?

JavaScript modules (import/export)
❯ CommonJS (require/exports)
None of these

13
Herramientas de desarrollo

? Which framework does your project use?

React
Vue.js
❯ None of these

? Where does your code run?

◯ Browser
❯◉ Node

? How would you like to define a style for your project?

❯ Use a popular style guide
Answer questions about your style
Inspect your JavaScript file(s)

? Which style guide do you want to follow?

❯ Airbnb (https://github.com/airbnb/javascript)
Standard (https://github.com/standard/standard)
Google (https://github.com/google/eslint-config-google)

? What format do you want your config file to be in?

JavaScript
YAML
❯ JSON

Checking peerDependencies of eslint-config-airbnb-base@latest

The config that you've selected requires the following dependencies:

eslint-config-airbnb-base@latest eslint@^4.19.1 || ^5.3.0 eslint-plugin-import@^2.14.0

? Would you like to install them now with npm? (Y/n) Y

Una vez finalizado el proceso creará un archivo en la raíz de nuestro proyecto llamado
.eslintrc.json , el cual contiene toda la configuración. Adicionalmente vamos a añadir las
siguientes excepciones:

1. Vamos a utilizar el objeto global console para imprimir muchos mensajes en la

consola y no queremos que lo marque como error.
2. A modo de ejemplo más adelante vamos añadir un parámetro que no utilizaremos
inmediatamente pero nos servirá mucho para explicar un concepto el cual es next y no
queremos que no los marque como error.

14
Herramientas de desarrollo

{
"env": {
"commonjs": true,
"es6": true,
"node": true
},
"extends": "airbnb-base",
"globals": {
"Atomics": "readonly",
"SharedArrayBuffer": "readonly"
},
"parserOptions": {
"ecmaVersion": 2018
},
"rules": {
"no-console": "off",
"no-unused-vars": [
"error",
{
"argsIgnorePattern": "next"
}
]
}
}

Antes de finalizar hacemos commit de nuestro trabajo

git add --all

git commit -m "Add ESLint for development"

Más información:

ESLint

Visual Studio Code

Para añadir nuestra configuración personalizada para el proyecto primero se debe crear el
directorio y el archivo de configuración:

mkdir .vscode
touch .vscode/settings.json

Dentro del archivo de configuración settings.json colocamos la siguiente información:

15
Herramientas de desarrollo

{
"editor.formatOnSave": true,
"editor.renderWhitespace": "all",
"editor.renderControlCharacters": true,
"editor.trimAutoWhitespace": true,
"editor.tabSize": 2,
"files.insertFinalNewline": true,
"files.eol": "\n",
"prettier.trailingComma": "es5",
"prettier.eslintIntegration": true
}

Si estás utilizando Visual Studio Code puedes añadir estos parámetros en la configuración:

Establecer que siempre se ordene el documento a la hora de guardar el archivo, que

muestre todos los espacios en blanco y caracteres especiales y remueva todos los
espacios en blanco que sobren.
Dejar una línea en blanco al final de cada archivo (requerido por defecto por ESLint) e
indicar cuál será el carácter de fin de línea, esto más que todo para retrocompatibilidad
con los sistemas Windows.
Si tienes el plugin de Prettier para ordenar el documento puedes indicarle que tome las
reglas de la configuración ESLint que tienes en el proyecto.
Finalmente si deseas añadir una coma al final de algunas estructuras de JavaScript
puedes indicarle a prettier que lo haga, esta es una buena práctica cuando se utiliza git
y cada línea nueva no necesita añadir una coma en el elemento anterior.

Es posible establecer unos plugins sugeridos para que una vez el programador abra el
proyecto en Visual Studio Code muestra la sugerencia:

touch .vscode/extensions.json

Con el siguiente contenido:

{
"recommendations": [
"waderyan.nodejs-extension-pack",
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
]
}

Depuración con Visual Studio Code

Crear el archivo de configuración:

16
Herramientas de desarrollo

touch .vscode/launch.json

Con la siguiente información:

{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "attach",
"name": "Node: Nodemon",
"processId": "${command:PickProcess}",
"restart": true,
"protocol": "inspector"
}
]
}

Luego modificamos la sección de scripts del archivo package.json para añadir la opción
que permitirá hacer debug al nodemon:

"scripts": {
"dev": "nodemon --inspect",
"start": "node index",
"test": "echo \"Error: no test specified\" && exit 1"
},

Se debe detener el Servidor una vez más para tomar los últimos cambios.

Antes de finalizar hacemos commit de nuestro trabajo:

git add --all

git commit -m "Add config for debugging with VSCode"

Más información:

VS Code - Nodemon

17
Crear un simple Web Server

Creando un simple Web Server

Antes de comenzar el proyecto vamos a crear un servidor Web sencillo, ya que nuestra
aplicación será una REST API Web que se podrá consumir mediante el protocolo HTTP,
será un API para administrar un listado de tareas de cada usuario y que opcionalmente se
pueden organizar en grupos, todo lo anterior con persistencia de datos.

Tomaremos el ejemplo del Web Server que se encuentra en la documentación de Node.js y

reemplazamos el contenido por el siguiente código:

// index.js

const http = require('http');

const hostname = '127.0.0.1';

const port = 3000;

const server = http.createServer((req, res) => {

res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello World');
});

server.listen(port, hostname, () => {

console.log(`Server running at http://${hostname}:${port}/`);
});

En el ejemplo anterior Node.js utiliza el módulo de http para crear un servidor Web que
escuchará todas las peticiones en la dirección IP y puerto establecidos, como es un ejemplo
responderá a cualquier solicitud con la cadena Hello World en texto plano sin formato,
solo para mostrar que el servidor Web está funcionando accedemos al navegador en la
siguiente dirección:

http://localhost:3000/

Normalmente en un REST API Web se consume mediante el protocolo HTTP y la respuesta

son objetos en formato JSON (el cual introduciremos más adelante), organizado en una
serie de rutas que adicionalmente reciben parámetros, el contrato para establecer la
relación entre las acciones del REST API Web y los verbos HTTP es bastante
estandarizada, pero no la estructura de la respuesta y la organización de la rutas, en esta
aplicación comenzaremos con una estructura sugerida que irá cambiando dependiendo los
diferentes casos y necesidades que se presenten.

18
Crear un simple Web Server

Antes de finalizar hacemos commit de nuestro trabajo:

git add index.js

git commit -m "Create a simple Web server"

Más información:

HTTP

19
Utilizando Express JS

Utilizando Express JS
Express JS es un librería con un alto nivel de popularidad en la comunidad de Node.js e
inclusive esta mismo adoptó Express JS dentro de su ecosistema, lo cual le brinda un
soporte adicional, pero esto no quiere decir que sea la única o la mejor, aunque existen
muchas otras librerías y frameworks para crear REST API, Express JS si es la más sencilla
y poderosa, según la definición en la página Web de Express JS: "Con miles de métodos de
programa de utilidad HTTP y middleware a su disposición, la creación de una API sólida es
rápida y sencilla."

Añadiendo Express JS
Instalamos el módulo de express como una dependencia de nuestra aplicación:

npm install -S express

Esto añadirá una nueva entrada en nuestro archivo package.json en la sección de

dependencies indicando la versión instalada.

Creamos un directorio llamado server donde se almacenarán todos los archivos

relacionados con el servidor Web así como su nombre lo indica:

mkdir server
touch server/index.js

Tomaremos como ventaja la convención de Node.js en la nomenclatura de los módulos

de la raíz de cada carpeta llamándolos index.js

Tomaremos el ejemplo de Hello World que se encuentra en la documentación de Express

JS y reemplazamos el contenido del archivo por el siguiente código:

20
Utilizando Express JS

// server/index.js

const express = require('express');

const port = 3000;

const app = express();

app.get('/', (req, res) => {

res.send('Hello World!');
});

app.listen(port, () => {
console.log(`Example app listening on port ${port}!`);
});

Como lo vemos es muy similar al anterior pero con una sutiles diferencias:

Utilizamos la librería de express en vez del módulo http .

Creamos una aplicación de express (inclusive se pueden crear varias) y la
almacenamos en la variable app .
Esta vez solo aceptaremos peticiones en la raíz del proyecto con el verbo GET de
HTTP.

Si el servidor se está ejecutando lo detenemos con CTRL+C , lo ejecutamos nuevamente con

el comando node server/index y abrimos el navegador en la siguiente dirección
http://localhost:3000/ . Luego volvemos a ejecutar la aplicación en modo de desarrollo.

Aparentemente vemos el mismo resultado, pero express nos ha brindado un poco más de
simplicidad en el código y ha incorporado una gran cantidad de funcionalidades, las cuales
veremos más adelante.

Organizando la aplicación
Antes de continuar vamos a organizar nuestra aplicación, crearemos diferentes módulos
cada uno con su propósito específico, ya que esto permite separar la responsabilidad de
cada uno de ellos, organizarlos en directorios para agrupar los diferentes módulos con
funcionalidad común, así nuestro archivo index.js será más ligero, legible y estructurado,
ya que NO es una buena práctica colocar todo el código en un solo archivo que sería difícil
de mantener, esto se le conoce como aplicación monolítica.

Empezamos organizando la aplicación de Express JS:

21
Utilizando Express JS

// server/index.js

const express = require('express');

const app = express();

app.get('/', (req, res) => {

res.send('Hello World');
});

module.exports = app;

Como podemos observar ahora nuestra aplicación de express es un módulo que tiene una
sola responsabilidad de crear nuestra aplicación y es independiente a la librería que
utilizamos.

Creamos el directorio y módulo básico de configuración:

mkdir -p server/config
touch server/config/index.js

En el archivo de configuración es donde centralizamos todas las configuraciones de la

aplicación que hasta el momento tenemos, así cualquier cambio será en un solo archivo y
no en varios, finalmente lo exportamos como un módulo:

// server/config/index.js

const config = {
server: {
port: 3000,
},
};

module.exports = config;

Para esta aplicación el hostname no es obligatorio, por lo cual lo omitimos en la

configuración.

De vuelta en nuestro archivo raíz, lo reescribimos quitándole las múltiples responsabilidades

que tenía y dejándolo solo con la responsabilidad de iniciar cada uno de los componentes
de la aplicación, utilizando los módulos creados posteriormente:

22
Utilizando Express JS

// index.js

const http = require('http');

const app = require('./server');

const config = require('./server/config');

const { port } = config.server;

const server = http.createServer(app);

server.listen(port, () => {
console.log(`Server running at port: ${port}`);
});

Como podemos observar la librería http es compatible con la versión de servidor nuestra
aplicación ( app ) creada por Express JS, que se crea en la función createServer e
inclusive si en el futuro fuera a incorporar un servidor https , solo es incluir la librería y
duplicar la línea de creación del servidor.

Reiniciamos nuestro servidor e iniciamos en modo desarrollo:

npm run dev

Si visitamos nuevamente el navegador en la dirección http://localhost:3000 todo debe

estar funcionando sin ningún problema.

Antes de finalizar hacemos commit de nuestro trabajo

git add --all

git commit -m "Add Express JS and configuration file"

Más información:

Express JS

23
Configuración y variables de entorno

Configuración y variables de entorno

Cross-env
Nuestra aplicación no siempre se ejecutará en ambiente desarrollo, por lo cual debemos
establecer cuál es el ambiente en que se está ejecutando y dependiendo de ello podemos
utilizar diferentes tipos de configuración e incluso conectarnos a diferentes fuentes de datos,
para ello vamos a utilizar la variable de entorno process.NODE_ENV, que puede ser accedida
desde cualquier parte de nuestra aplicación por el objeto global process .

Es muy importante garantizar la compatibilidad entre los diferentes sistemas operativos ya

que cada sistema establece las variables de manera diferente, para asegurar que funcione
en diferentes sistemas operativos utilizaremos una librería de npm llamada cross-env , la
instalamos como una dependencia de nuestra proyecto y así aseguramos que siempre esté
disponible en nuestra aplicación:

npm i -S cross-env

Entonces finalmente para utilizarla modificaremos nuestros npm scripts en el archivo

package.json de la siguiente manera:

"scripts": {
"dev": "cross-env NODE_ENV=development nodemon --inspect",
"start": "cross-env NODE_ENV=production node index",
"test": "cross-env NODE_ENV=test echo \"Error: no test specified\"&& exit 1"
},

Antes de finalizar hacemos commit de nuestro trabajo:

git add --all

git commit -m "Add cross-env and setting the environments"

Más información acerca de:

process
cross-env

Dotenv

24
Configuración y variables de entorno

En este momento nuestras variables de configuración están almacenadas en un archivo

JavaScript y sus valores están marcados en el código fuente de la aplicación, lo cual NO es
una buena práctica pues se estaría exponiendo datos sensibles, la idea es extraer esta
información y tenerla en archivos separados por entorno pues no es la misma base de
datos de desarrollo que la de producción.

Ahora debemos distinguir que es configuración de sistema y del usuario, la primera son
valores que necesita la aplicación para funcionar como: numero del puerto, la dirección IP y
demás, las segundas son más relacionadas con la personalización de la aplicación como:
número de objetos por página, personalización de la respuesta al usuario, etc.

Utilizaremos una librería que nos permite hacer esto muy fácil llamada dotenv, que nos
carga todas las variables especificadas en un archivo a el entorno de Node JS, procedemos
a crear el archivo de configuración en la raíz del proyecto llamado .env y le colocamos el
siguiente contenido:

SERVER_PORT=3000

Instalamos la librería:

npm i -S dotenv

Procedemos a modificar nuestro archivo de configuración:

// server/config/index.js

require('dotenv').config('');

const config = {
server: {
port: process.env.SERVER_PORT || 3000,
},
};

module.exports = config;

Como podemos ver por defecto la librería dotenv buscará el archivo llamado .env ,
cargará las variables y su valores en el entorno del proceso donde se está ejecutando Node
JS. Así nuestra configuración del sistema no estará más en el código fuente de la aplicación
y adicional podemos reemplazar el archivo de configuración en cada entorno donde se
publique la aplicación.

25
Configuración y variables de entorno

Antes de terminar un aspecto muy importante es NO incluir el archivo de configuración

.env en el repositorio de git, pues esto es justo lo que queremos evitar: que nuestra
configuración y valores no quede en el código fuente de la aplicación, para ello modificamos
el archivo .gitignore de la siguiente forma:

node_modules/
.DS_Store
.Thumbs.db
.env

Como no estamos guardando este archivo en nuestro repositorio, crearemos una copia de
ejemplo para que el usuario pueda renombrarlo y utilizarlo:

cp .env .env.example

Antes de finalizar hacemos commit de nuestro trabajo:

git add --all

git commit -m "Add dotenv, .env file and set in the configuration file"

Más información acerca de:

dotenv

26
Middleware para manejo de errores

Middleware para manejo de errores

Hasta el momento la única ruta que tenemos configurada en nuestro proyecto con express
es / (La raíz del proyecto) y con el método GET, pero ¿Qué sucede si tratamos de
acceder otra ruta?. Pues en este momento no tenemos configurado como manejar esta
excepción, en términos de express no existe ningún "Middleware" que la procese, por lo
tanto terminará en un error no manejado por el usuario.

Si vamos al navegador y tratamos de acceder a una ruta como localhost:3000/posts

obtendremos un resultado generico cómo: Cannot GET /posts y un código HTTP 404 que
indica que el recurso no fue encontrado, pero nosotros podemos controlar esto con express,
primero analizemos el fragmento de código que define la ruta:

app.get('/', (req, res) => {

res.send('Hello World');
});

1. La aplicación ( app ) adjunta una función callback para cuando se realice una petición a
la ruta / con el método GET.
2. Esta función callback recibe dos argumentos: el objeto de la petición (request)
abreviado req y el objeto de la respuesta (response) abreviado res .
3. Una vez se cumplen los criterios establecidos en la definición de la ruta la función de
callback es ejecutada.
4. Se envía la respuesta por parte del servidor ( res.send('Hello world') ) el flujo de esta
petición se detiene y el servidor queda escuchando por más peticiones.

Express middleware
"Las funciones de middleware son funciones que tienen acceso al objeto de solicitud (req),
al objeto de respuesta (res) y a la siguiente función de middleware en el ciclo de
solicitud/respuestas de la aplicación. La siguiente función de middleware se denota
normalmente con una variable denominada next."

(Tomado de Utilización de middleware)

Esto quiere decir que nuestro callback en realidad es una función middleware de express y
tiene la siguiente firma de parámetros:

27
Middleware para manejo de errores

app.get('/', (req, res, next) => {

res.send('Hello World');
});

Dónde next es otra función que al invocarse permite continuar el flujo que habíamos
mencionado antes para que otras funciones middleware pueden continuar con el
procesamiento de la petición.

Esto quiere decir que podemos agregar otro middleware al final del flujo para capturar si la
ruta no fue procesada por ningún middleware definido anteriormente:

// server/index.js

const express = require('express');

const app = express();

app.get('/', (req, res, next) => {

res.send('Hello World');
});

// No route found handler

app.use((req, res, next) => {
res.status(404);
res.json({
message: 'Error. Route not found',
});
});

module.exports = app;

Nótese varias cosas importantes en el fragmento de código anterior:

1. Se ha agregado la función next al middleware de la ruta raíz, pero realmente no lo

estamos utilizando dentro de la función, pero esto es con el fin hacer concordancia con
la firma que tienen las funciones middleware (Más adelante la editaremos)
2. Le hemos indicado a la aplicación ( app ) utilizar una función middleware, nuevamente
podemos saber que es una función middleware de express por su firma, revisando los
parámetros.
3. Estamos estableciendo el código HTTP de la respuesta con res.status(404) el cual
equivalente a una página no encontrada, en este caso una ruta o recurso.
4. Cuando un servidor Web responde debe indicar el tipo de contenido que está
devolviendo al cliente (por ejemplo: Navegador Web) para que esté a su vez puede
interpretarlo y mostrarlo al usuario, esto se indica en la respuesta mediante el
encabezado Content-type , por defecto el valor es text/plain que se utiliza para texto

28
Middleware para manejo de errores

plano o text/html para código HTML, cada uno de estos valores se conoce como el
MIME Type de los archivos. En este caso estamos respondiendo explícitamente un
objeto tipo JSON como lo indicamos en la función res.json() , no tenemos necesidad
de establecer el Content-Type , pues express lo hace automáticamente por nosotros a
application/json y adicionalmente convierte el objeto literal de JavaScript a un objeto
JSON como tal.

Guardamos el archivo (nodemon reiniciará nuestra aplicación automáticamente ) y ahora si

vamos nuevamente al navegador e invocamos nuevamente la ruta localhost:3000/posts

obtendremos el mensaje que establecimos en el middleware que se convierte en la última

función de middleware de todos las declaradas anteriormente en esta aplicación de
express:

{
message: 'Error. Route not found'
}

Para hacer una analogía a la definición de los middleware es como una cola de funciones
donde la petición se revisa desde comenzando desde la primera función, si el middleware
coincide con la petición este detiene el flujo, procesa la petición y puede hacer dos cosas:
dar respuesta a la petición y en este caso se detiene la revisión por completo o dejar pasar
la petición al siguiente middleware esto se hace con la función next, o de lo contrario si
ninguna coincide llegará al final que es el middleware genérico para capturar todas las
peticiones que no se pudieron procesar antes.

Manejo de errores
Ahora surge la siguiente pregunta, ¿Cómo podemos controlar los errores que sucedan en
las diferentes rutas?, express permite definir una función middleware con una firma de
parámetros un poco diferente a las anteriores, introducimos el siguiente código al final:

29
Middleware para manejo de errores

// server/index.js

...

// Error handler
app.use((err, req, res, next) => {
const {
statusCode = 500,
message,
} = err;

res.status(statusCode);
res.json({
message,
});
});

module.exports = app;

Los ... en el código indica que hay código anterior en el archivo

Podemos ver varias cosas en el código anterior:

1. El middleware que captura errores en express comienza por el parámetro de error

abreviado como err

2. Obtenemos el statusCode del objeto err , si no trae ninguno lo establecemos en 500

por defecto que significa Internal Server Error, así como el message que este trae.
3. Finalmente establecemos el StatusCode en la respuesta ( res ) y enviamos de vuelta
un JSON con el mensaje del error.

Ahora cada vez que invoquemos un error en cualquier middleware tendremos uno que lo
capture y procese, podríamos aprovechar esto, por ejemplo, para guardar en los logs
información relevante del error.

Para terminar cambiamos nuevamente la definición de la ruta raíz de la siguiente manera:

...

app.get('/', (req, res, next) => {

res.json({
message: 'Welcome to the API',
});
});

...

30
Middleware para manejo de errores

Nótese que ahora estamos devolviendo un archivo JSON, pues estamos creando un REST
API Web.

Antes de continuar guardemos nuestro progreso:

git add --all

git commit -m "Add middleware for not found routes and errors"

31
Sistema de Logs

Sistema de Logs

Utilizar Winston para los logs

Es importante para cualquier aplicación que va a salir a producción tener un sistema de
logs, pues cuando estamos en desarrollo tenemos el control total y es muy fácil investigar
para averiguar si existe algún error, lo que no sucede cuando la aplicación está
ejecutándose en producción, por lo tanto el sistema de logs es una manera eficaz de dejar
rastro de las operaciones, advertencias o errores que puedan suceder en la aplicación.

Existen muchas librerías que son de mucha utilidad así como express, entre ellos está
Winston, el cual nos permite crear un log personalizado con múltiples métodos para
manejar los logs desde imprimirlos en la consola hasta guardarlos en archivos.

Procedemos a instalar las dependencias

npm install -S winston

Debemos crear un nuevo archivo para establecer la configuración de los logs, estoy es muy
importante si en el día de mañana se quiere cambiar de configuración o inclusive de librería
el resto de la aplicación no debería verse afectada.

Creamos el archivo con su respectivo contenido:

// server/config/logger.js

const { createLogger, format, transports } = require('winston');

// Setup logger
const logger = createLogger({
format: format.simple(),
transports: [new transports.Console()],
});

module.exports = logger;

Como pueden observar hemos decidido para este proyecto imprimir los logs en la consola,
pero como mencionamos antes esta librería nos permite almacenarlos en archivos, si así lo
deseamos.

32
Sistema de Logs

// server/index.js

const express = require('express');

const logger = require('./config/logger');

// Init app
const app = express();

// Routes
app.get('/', (req, res, next) => {
res.json({
message: 'Welcome to the API',
});
});

// No route found handler

app.use((req, res, next) => {
const message = 'Route not found';
const statusCode = 404;

logger.warn(message);

res.status(statusCode);
res.json({
message,
});
});

// Error handler
app.use((err, req, res, next) => {
const { statusCode = 500, message } = err;

logger.error(message);

res.status(statusCode);
res.json({
message,
});
});

module.exports = app;

Como podemos observar en el fragmento de código anterior incluimos nuestro logger y lo

utilizamos en los middleware.

Antes de continuar guardemos nuestro progreso:

git add --all

git commit -m "Add Winston to create log system"

33
Sistema de Logs

Más información:

Winston

Utilizar morgan para hacer logs de las

peticiones
La librería anterior nos permitió crear un log personalizado, pero también debemos a
registrar el acceso a todas las peticiones dándonos un detalle de lo que se está recibiendo
en el servidor, para esto vamos a utilizar la librería de morgan, procedemos a instalarla de la
siguiente manera:

npm install -S morgan

Morgan finalmente es un middleware que tomará las peticiones y las imprimirá según
nosotros le indiquemos:

// server/index.js

const express = require('express');

const morgan = require('morgan');

const logger = require('./config/logger');

// Init app
const app = express();

// Setup middleware
app.use(morgan('combined'));

// Routes
app.get('/', (req, res, next) => {
res.json({
message: 'Welcome to the API',
});
});

...

Incluimos morgan como un middleware, probamos accediendo a diferentes URL y vemos el

resultado en la consola, pero tenemos dos salidas de logs: una producida por winston y otra
por morgan, que casualmente ambas están saliendo a la consola por lo tanto añadimos la
siguiente configuración adicional:

34
Sistema de Logs

// server/index.js

...

// Setup middleware
app.use(morgan('combined', { stream: { write: message => logger.info(message) } }));

...

Resulta y pasa que por defecto morgan coloca sus logs en la consola, pero nosotros le
estamos indicando que utilice el logger que creamos con winston, finalmente irán a la
consola, pero esta vez es un solo manejador de logs, que si decidimos guardarlos en
archivos, nuevamente el cambio sería solamente en una sola parte.

Si abrimos el navegador e invocamos diferentes rutas en la dirección del navegador Web

podremos ver en la consola las diferentes peticiones que llegan al servidor y también los
mensajes personalizados que imprimimos en los middleware.

Antes de continuar guardemos nuestro progreso:

git add --all

git commit -m "Add morgan to log the app requests"

Más información:

Morgan

Hacer seguimiento a las peticiones

Nuevamente cuando nuestra aplicación está ejecutándose en producción llegan
muchísimas peticiones al mismo tiempo y si deseamos identificar una en particular va a
hacer muy difícil, para ello debemos identificar cada uno de ellas, utilizaremos una librería
para ello llamada express-request-id que añade a la petición entrante (req) un campo
llamado id donde su valor es un número único y en la petición de respuesta (res) establece
el encabezado X-Request-Id con el mismo valor para que el cliente pueda identificar la
petición.

procedemos a instalarla de la siguiente manera:

npm install -S express-request-id

La incluimos en nuestro archivo del servidor:

35
Sistema de Logs

// server/index.js

const express = require('express');

const morgan = require('morgan');
const requestId = require('express-request-id')();

const logger = require('./config/logger');

// Init app
const app = express();

// Setup middleware
app.use(requestId);
app.use(morgan('combined', { stream: { write: message => logger.info(message) } }));

...

Al redirigir los mensajes de morgan a winston las peticiones siempre agregan un final de
línea, por lo tanto vamos a removerlo con la siguiente librería:

npm i -S strip-final-newline

Ahora debemos incluirla en nuestro log de morgan, por lo tanto vamos a mover morgan a
nuestro archivo de logger y lo editamos de la siguiente manera:

36
Sistema de Logs

// server/config/logger.js

const { createLogger, format, transports } = require('winston');

const morgan = require('morgan');
const stripFinalNewline = require('strip-final-newline');

// Setup logger
const logger = createLogger({
format: format.simple(),
transports: [new transports.Console()],
});

// Setup requests logger

morgan.token('id', req => req.id);

const requestFormat = ':remote-addr [:date[iso]] :id ":method :url" :status';

const requests = morgan(requestFormat, {
stream: {
write: (message) => {
// Remove all line breaks
const log = stripFinalNewline(message);
return logger.info(log);
},
},
});

// Attach to logger object

logger.requests = requests;

module.exports = logger;

Explicamos a continuación los cambios:

Le indicamos a morgan como va a calcular el token :id , que como vimos

anteriormente nuestra nueva librería lo agrega al objeto req .
Establecemos un formato personalizado basado en el combined que trae por defecto y
añadimos el token :id .
Eliminamos todos los saltos de línea y guardamos toda la configuración de morgan en
la variable requests .
Finalmente guardamos dentro de logger la configuración de morgan, pues recordemos
que debemos añadirla como middleware de express en el archivo del servidor.

Actualizamos nuevamente nuestro archivo del servidor:

37
Sistema de Logs

// server/index.js

const express = require('express');

const requestId = require('express-request-id')();

const logger = require('./config/logger');

// Init app
const app = express();

// Setup middleware
app.use(requestId);
app.use(logger.requests);

...

Antes de continuar guardemos nuestro progreso:

git add --all

git commit -m "Add Request id to identify the request with morgan"

Más información:

express-request-id

Añadir formato de la petición a los logs

En este momento los logs generados por morgan al recibir las peticiones tienen una
información adicional de la petición como: Dirección IP del cliente, fecha y hora, el método
HTTP y la URL, añadimos un función que reciba la petición como parámetro y nos devuelva
la misma información:

// server/config/logger.js

...

// Attach to logger object

logger.requests = requests;

// Format as request logger and attach to logger object

logger.header = (req) => {
const date = new Date().toISOString();
return `${req.ip} [${date}] ${req.id} "${req.method} ${req.originalUrl}"`;
};

module.exports = logger;

38
Sistema de Logs

A continuación vamos a realizar las siguientes modificaciones en nuestro archivo del

servidor en los dos middleware asociados a errores:

// server/index.js

...

// No route found handler

app.use((req, res, next) => {
next({
message: 'Route not found',
statusCode: 404,
level: 'warn',
});
});

// Error handler
app.use((err, req, res, next) => {
const { message, statusCode = 500, level = 'error' } = err;
const log = `${logger.header(req)} ${statusCode} ${message}`;

logger[level](log);

res.status(statusCode);
res.json({
message,
});
});

module.exports = app;

Lo primero que podemos observar es que ahora el middleware que nos captura cuando una
ruta no es encontrada está invocando el siguiente middleware ( next ) con el información
del error y finalmente en procesado por nuestro middleware asociado con los errores, donde
creamos la cadena de log basada en la función que acabamos de crear, una nueva
modificación es el type que por defecto es error si no es enviada en el objeto de error .

Si vamos al navegador e invocamos una dirección que no existe sobre nuestra API
podemos ver el resultado en los logs.

Antes de continuar guardemos nuestro progreso

git add --all

git commit -m "Add log header from requests"

39