Construir un API REST con NodeJS (Tercera parte)

Construir un API REST con NodeJS - Tercera parteEste art铆culo es la tercera parte del articulo original (Segunda parte), en la cual hablamos de los HTTP Verbs, su importancia, funcionalidad y c贸mo implementarla en nuestro API utilizando NodeJS + Express. En esta tercera parte, hablaremos acerca de los URL paths, c贸mo es posible crear URL parametrizadas y la forma de recuperar los par谩metros del objeto request.

URL Paths

Uno de los aspectos m谩s importantes de un servicio REST, es su URL, primero que nada, porque es la forma en que podemos consumir el servicio, pero tambi茅n es importante por le da al usuario una pista significativa acerca de su funcionalidad. Una URL bien definida, podr铆a decirle al usuario para que sirve con una precisi贸n muy acertada, sin tener que recurrir a la documentaci贸n.

Para que una URL tenga un significado real, es necesario complementarlo con m茅todo (o verb) al que responde, pues el m茅todo nos dice el tipo de operaci贸n que va a realizar, mientras que la URL nos dice que es lo que va hacer. Analicemos las siguientes URL:

GET/users/oscar/avatar
PUT/users/oscar/avatar
DELETE/users/oscar
POST/users

Quiero que te tomes solo un momento para analizar las URL anteriores鈥 te aseguro que sin ser un experto pudiste adivinar con gran certeza que hace cada una de estas operaciones. Si no, te recomiendo ver la segunda parte de este art铆culo para refrescar un poco la memoria.

Como sea, vamos a explicar que hace cada una, en la primera URL, sabemos que el GET se utiliza para consultas y la URL habla de usuarios, luego un nombre y finalmente un avatar, por lo que podemos deducir que este servicio est谩 realizando la consulta del Avatar del usuario oscar, 驴vez que f谩cil?

En la segunda URL, sabemos que PUT se utiliza para realizar updates, por lo tanto, le estamos diciendo que actualice el Avatar del usuario oscar.

En la tercera URL, sabemos que DELETE se utiliza para borrar un registro, por lo que est谩 de m谩s decir que lo que hace es borrar el usuario oscar.

En la cuarta URL, sabemos que POST se utiliza para crear un nuevo registro y est谩 invocando solamente /users, esto me dice que el servicio est谩 creando un nuevo usuario.

Con Express es realmente f谩cil implementar estas URL, tan solo hay que definir los Routers con el m茅todo adecuado y con el URL al que debe procesar, veamos c贸mo quedar铆a:

Los paths siempre deben de representar exactamente lo que hacen, y el m茅todo debe de corresponder con la acci贸n que realizar谩, pues no hacerlo, puede confundir a los desarrolladores.

Prioridad de los paths

Un error al momento de iniciar con Express es pensar que el orden en que se definen los Routers es irrelevante, como si de una funci贸n se tratara, la cual puede ser llamada desde donde sea y siempre se ejecuta la correcta, sin embargo, esto no es cierto. Por este motivo, Express evaluar los Router en el orden en que est谩n definidos.

Existe ocasiones en que m谩s de una URL puede colisionar y entrar en el Path equivocado, por ejemplo, las siguientes dos URL:

GET: /*

GET:/login

La primera acepta cualquier URL, porque tiene un comod铆n (*), mientras que la segunda, solo acepta la URL /login. En este caso, como /* esta primero, entonces atender谩 las peticiones que lleguen a /login, porque el path /* cumple con el patr贸n, en tal caso, tendr铆amos que invertir el orden de los Routers de la siguiente manera:

GET:/login

GET: /*

De esta forma, cuando llegue una petici贸n a /login, la tomar谩 el primer Router y para todos los dem谩s path ser谩 /* quien procese la solicitud.

URL Params

Una de las caracter铆sticas de REST, es la posibilidad de convertir ciertas partes de una URL en par谩metro, de tal forma que nos ahorra tener que escribir una URL para cada registro que necesitemos.

Regresando al ejemplo de los servicios para usuarios GET: /users/oscar, podemos apreciar que 鈥渙scar鈥 esta fija en la URL, lo que provocar铆a que tuvi茅ramos que tener un Router para cada usuario registrado. Por suerte, Express nos permite escribir URL Params. Para convertir una secci贸n de la URL en URL param, solo tendremos que anteponer dos puntos (:) antes, por ejemplo:

/users/:username

/users/:username/:field

En la primera URL podr铆amos recibir consultas para todos los usuarios, por ejemplo:

/users/oscar聽, /users/juan聽, /users/pedro

Mientras que en la segunda URL podr铆amos consultar cualquier campo del usuario, por ejemplo:

/users/oscar/avatar聽 o /users/juan/banner

Para recuperar los URL Params, tan solo es necesario recuperarlos del objeto request de la siguiente manera: req.params.<name>. Veamos algunos ejemplos:

API REST - URL Params

Query params

Los query params son lo m谩s conocidas, y son todos aquellos que van al final de la URL seguido del s铆mbolo de interrogaci贸n (?). Se pueden enviar cuantos Query params se requiere, siempre y cuando no excedamos el l铆mite m谩ximo de caracteres para un URL. Cada par谩metro deber谩 est谩 separado un el s铆mbolo de ampersand (&). Algunos ejemplos:

/cources?coupon=FREE&Source=Google

Este tipo de par谩metros es muy com煤n en campa帽as publicitarias, pues el param coupon determina que el curso a comprar es gratis (free), mientras que el param Source nos dice de donde llego el cliente (google).

Para recuperar un Query param en Express se usa la siguiente sentencia, req.query.<parama-name>. Veamos c贸mo implementarlo en Express.

Si ejecutamos la URL /cources?coupon=FREE&Source=Google聽 obtendremos el siguiente resultado:

API REST - query params

驴Te gustar铆a aprender las t茅cnicas m谩s avanzadas para crear API REST con NodeJS? Te invito a que veas mi libro 鈥淎plicaciones reactivas con React, NodeJS & MongoDB鈥, donde aprender谩s a crear una API REST completo, desde exponer los servicios hasta habilitar la seguridad con JSON Web Token (JTW)

Body params

El tercer y 煤ltimo tipo de par谩metro que podemos enviarle a un servicio REST, es el payload (o body), el cual puede ser un mensaje largo que no se puede ver a simple vista. No todos los m茅todos HTTP soportan el env铆o de un payload, por lo que hay que tener eso en cuenta.

De los m茅todos m谩s utilizados que soportan el env铆o de un payload son: POST, PUT, PATCH, DELETE. Observa que el m茅todo GET no lo soporta.

Recuperar el body del request no est谩 simple como parecer铆a, pues en realidad, este par谩metro es un InputStream, lo que quiere decir, que se recibe como los datos poco a poco y no todo de una. Esto nos obliga a procesar el payload a medida que va llegando. Este proceso lo podemos simplificar con ayuda del m贸dulo body-parser, el cual instalamos en la primera parte de este art铆culo (npm install –save body-parser).

Mediante este m贸dulo, es posible convertir el payload en varios formatos, pero el que nos interesa es JSON, pues es el est谩ndar para REST. Configurarlo, solo tendremos que importarlo y agregar un middleware (los analizaremos m谩s adelante).

API REST - Body param

Finalmente, existe una 煤ltima forma de recibir informaci贸n para el API, la cual es a trav茅s de Header, sin embargo, esta parte la dejaremos para la siguiente parte, en la cual hablaremos de la autenticaci贸n mediante JSON Web Tokens (JWT).

8 thoughts to “Construir un API REST con NodeJS (Tercera parte)”

  1. Excelente paso a paso de construccion REST API. Les pido su amable colaboracion con el siguiente apunte:
    tengo entendido que en un proyecto que involucra Frontend, API REST y BD, los tres pueden hospedarse en servidores separados. En un proyecto que estoy construyendo, los tres mencionados los tengo en el mismo servidor. Para la prueba en mi PC me funciona la API simple ejecucion en consola de “node apirest.js”, y frontend en el navegador. Pero para publicar en un servidor remoto no encuentro forma de arrancar la API. Le he construido un componente a manera de aplicacion en Angular pero no logro hacerlo funcionar. Puede darme ideas. Gracias por la valiosa colaboracion.

    1. Hola Gilberto,
      Lo que mencionas es correcto, los 3 componentes pueden estar en servidores independientes, todo depender谩 de que arquitectura de servidores que funcione mejor, de la misma forma, puede tener los 3 juntos.
      Con respecto a por que no te funciona en el servidor remoto, bueno… puede hacer cientos de motivos por el cual no funcione, y es imposible decirte sin saber nada del error que te lanza al ejecutarlo.
      saludos.

  2. Entendido Oscar, seguro no fui especifico en la pregunta. Me refiero puntuamente a la forma de inicializar la API; si localmente la puedo ejecutar con el comando node apirest.js, remotamente como lo haria?. En mi PC tengo instalado node, en el servidor remoto y teniendo en cuenta que es un hosting rentado, que necesitaria?. Definitivamente debe hacerse con un html? o conoce alguna otra forma de inicializar la api?
    Gracias

Deja un comentario

Tu direcci贸n de correo electr贸nico no ser谩 publicada. Los campos obligatorios est谩n marcados con *