Te recomiendo que te des una venta a mi artículo Autenticación con JSON Web Tokens, el cual abordo toda la teoría, por si no estás familiarizado con el concepto de Tokens y la forma de trabajar.

Este artículo es parte de una colección de artículo en donde explico cómo Construir un API REST con NodeJS, por lo que si estas interesado puede regresar desde el comienzo.

Implementando JWT en un API REST

Lo primero será instalar el módulo de JWT, para lo cual, ejecutaremos el comando npm install –save jsonwebtoken body-parser , una vez hecho esto, tendremos que implementar un servicio de autenticación tradicional, el cual reciba usuario y contraseña y nos regrese un token en caso de éxito. El servicio quedaría de la siguiente manera:

var jwt = require('jsonwebtoken')
var bodyParser = require('body-parser')

app.use(bodyParser.urlencoded({extended: false}))
app.use(bodyParser.json({limit:'10mb'}))

app.post('/login', (req, res) => {
  var username = req.body.user
  var password = req.body.password

  if( !(username === 'oscar' && password === '1234')){
    res.status(401).send({
      error: 'usuario o contraseña inválidos'
    })
    return
  }

  var tokenData = {
    username: username
    // ANY DATA
  }

  var token = jwt.sign(tokenData, 'Secret Password', {
     expiresIn: 60 * 60 * 24 // expires in 24 hours
  })

  res.send({
    token
  })
})

La función login recibe como parámetro el usuario (req.body.user ) y el password (req.body.password ), los cuales los tendremos que validar contra nuestros usuarios, sin embargo, en este caso, para hacerlo más simple, lo hemos validado contra el usuario oscar/1234, si la autenticación falla, entonces regresamos un error al cliente. Por otra parte, si todo sale bien, creamos un token al usuario, el cual tiene una vigencia de 24 horas, para finalmente retornarlo.

Veamos un ejemplo de autenticación:

En la imagen pasada hemos enviado las credenciales correctas para que nos genere un token, sin embargo, no se puede ver correctamente debido a su longitud, es por ello que lo ponemos por a continuación:

{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6Im9zY2FyIiwiaWF0IjoxNTE2MDY4OTI4LCJleHAiOjE1MTYxNTUzMjh9.zucLW085AiZ8VWojwNFFcMz0yv1H4RbeCMQy7lVjS7s"
}

Este token deberá ser guardado por el usuario para futuras invocaciones al API.

Autenticándonos mediante Tokens

El siguiente paso será crear un servicio protegido que valida la existencia del token, de lo contrario, evitará el acceso, para ello crearemos un servicio de prueba llamado secure:

app.get('/secure', (req, res) => {
    var token = req.headers['authorization']
    if(!token){
        res.status(401).send({
          error: "Es necesario el token de autenticación"
        })
        return
    }

    token = token.replace('Bearer ', '')

    jwt.verify(token, 'Secret Password', function(err, user) {
      if (err) {
        res.status(401).send({
          error: 'Token inválido'
        })
      } else {
        res.send({
          message: 'Awwwww yeah!!!!'
        })
      }
    })
})

Como podemos observar, lo primero que tenemos que hacer, es recuperar el header correspondiente al token, es decir, el token “authorization ”, si este header no se encuentra, entonces retornamos un código 401 (No autorizado) y regresamos el motivo del error.

El siguiente paso es algo confuso, pues al token hay que retirarla el substring “Baerer  “, este String es parte de las especificaciones de HTTP, y es agredo de forma automática, por lo que no entraremos en detalles, simplemente lo retiramos.

Finalmente, validamos el token mediante el método verify, el cual validará que el token sea válido y además que no esté caducado, en cualquiera de estos dos casos, un error 401 es retornado junto con el mensaje de error. Finalmente, si todo sale bien, procedemos con la operación de negocio.

El siguiente request es enviado son el header, retornando un error 401 y su mensaje de error correspondiente:

Este nuevo request es enviado con el header ‘authorization ’ el cual corresponde a un token válido generado por el servicio de login:

NOTA: Siempre será mejor usar un middleware para validar el token, de esta forma, evitamos tener que validar el token en cada invocación, sin embargo, lo hemos hecho así para hacer más fácil el ejemplo.

The post Implementar JSON Web Tokens con NodeJS appeared first on Oscar Blancarte - Software Architecture.

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:

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:

app.get('/users/oscar/avatar', (req, res) => {
  res.send('Hello GET:/users/oscar/avatar')
})

app.put('/users/oscar/avatar', (req, res) => {
  res.send('Hello PUT:/users/oscar/avatar')
})

app.delete('/users/oscar', (req, res) => {
  res.send('Hello DELETE:/users/oscar')
})

app.post('/users', (req, res) => {
  res.send('Hello POST:/users')
})

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 “oscar” 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:

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.

app.get('/cources', (req, res) => {
  var coupon = req.query.coupon
  var source = req.query.source
  res.send("Coupo: " + coupon + ", Source: " + source)
})

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

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).

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).

The post Construir un API REST con NodeJS (Tercera parte) appeared first on Oscar Blancarte - Software Architecture.

También puedes ver como implementar los verbs con Java en mi guía de implementación de un API REST con Java.

Verbs

Uno de los conceptos más importantes cuando trabajamos con REST, son los Verbs (o también llamados métodos), los cuales conocemos como GET, POST, DELETE, PATCH, PULL, etc. determinan la acción que deseamos hacer sobre un determinado recurso. En REST, cada método tiene un significado para el API, pues una misma URL puede tener diferente significado dependiendo sobre el método se ejecutó.

Por ejemplo, la URL /user/oscar sobre el método GET, representa una consulta para el API, mientras que la misma URL sobre el método DELETE, representa una instrucción de borrar al usuario.

Los métodos (o verbs) más utilizados en un API REST son:

• GET: Se utiliza para realiza consultas (Select)
• POST: Se utiliza para crear nuevos registros (Insert)
• DELETE: Se utiliza para borrar un registro (Delete)
• PUT: Se utiliza para actualizar total o parcialmente un registro existente (Update)
• PATCH: Se utiliza para actualiza solo una pequeña parte de un registro existente (Update)

Puedes ver la lista completa de método soportados en la siguiente en la documentación oficial de Express.

Utilizando los verbs con Express

En express es realmente fácil crear servicio que atienda peticiones en los diferentes métodos, ya que proporciona una función para cada uno de ellos, el cual se define de la siguiente manera:

express.<verb>(<path>, <callback>)

El <verb> representa el método HTTP soportado por express en minúscula, el <path> es la ruta en la cual escucha las peticiones y el <callback> es la función que procesará las peticiones, la cual recibe dos parámetros, el primero es un objeto que representa el request y el segundo es el objeto que representa la respuesta, por ejemplo:

var express = require('express')
var http = require('http')
var app = express()

var users = ['oscar', 'juan', 'marcos']

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

app.get('/', (req, res) => {
  res.status(200).send("Welcome to API REST")
})

http.createServer(app).listen(8001, () => {
  console.log('Server started at http://localhost:8001');
});

Veamos las líneas 5 y 9, hemos definido dos Routers, los cuales atienden peticiones GET, sin embargo, las dos atienden en diferente path, por lo que si ejecutamos la URL http://localhost:8001/users tendremos un resultado diferente que ejecutar simplemente http://localhost:8001.

Al igual que tenemos Router para procesar peticiones GET, podemos agregar otros métodos, como, por ejemplo:

app.post('/users', (req, res) => {
  users.push('User ' + users.length)
  res.send("New user add")
})

Este nuevo Router atiende peticiones POST en el path /users, y tiene como funcionalidad agregar un nuevo usuario a la lista actual de usuario y retorna un mensaje al cliente. Desde luego que este servicio no lo podemos probar desde el navegador, por lo que utilizaremos el plugin Restlet de Chrome para probarlo, el resultado es el siguiente:

De esta forma, podemos agregar tantos métodos necesitemos para nuestra API, por ejemplo:

app.patch('/users',(req, res) => {
  res.send('PATCH method')
})

app.delete('/users',(req, res) => {
  res.send('DELETE method')
})

Como hemos visto hasta ahora, es posible definir una serie de Router capaces de atender en los diferentes métodos que ofrece Express, también hemos visto que es posible definir más de un Router con el mismo método para atender diferentes URL.

En la siguiente parte de este artículo hablaremos acerca de los paths y como parametrizarlos para atender en URL dinámicas.

Continuación (Tercera parte)

The post Construir un API REST con NodeJS (Segunda parte) appeared first on Oscar Blancarte - Software Architecture.

Si no sabes muy bien que es un API REST, te invito a que veas mi video un Youtube donde lo explico “Qué es API REST? – 🚀Y por que es importante aprenderlo 🚀”

Construir un API REST es realmente simple, y más aún, si cuentas con las tecnologías adecuadas. En este sentido, NodeJS + Express, se ha convertido en la combinación perfecta para realizar esta tarea, pues es posible construir y levantar un API REST en cuestión de segundos.

Preparando el proyecto

Lo primero será crear un nuevo proyecto desde el cual estaremos trabajando, para ello, crearemos una nueva carpeta en cualquier parte y nos ubicaremos en ella a por medio de la línea de comandos. Una vez allí, ejecutaremos el comando npm init , el cual nos solicitará algunos datos referentes al proyecto, al finalizar, nos habrá creado el archivo package.json y una carpeta llamada node_modules, la cual contiene todas las librerías estándar de NodeJS.

En este punto, tendremos que instalar los módulos de NPM que vamos a requerir, para ello, ejecutaremos los comandos:

• npm install –save express
• npm install –save body-parser

Express es el módulo más popular para desarrollos web en NodeJS y además, es especialmente útil para la construcción de API’s, por otra parte, el Middleware body-parse, que anteriormente era parte de Express, nos ayudará a procesar el payload (o body) del request, el cual nos lo dejar listo y en el formato que lo necesitamos, en este caso, en JSON.

En este punto, tendremos un archivo package.json  muy parecido al siguiente:

{
  "name": "api-rest",
  "version": "1.0.0",
  "description": "Mi primer API REST",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "API",
    "REST",
    "NodeJS"
  ],
  "author": "Oscar Blancarte",
  "license": "ISC",
  "dependencies": {
    "body-parser": "^1.18.2",
    "express": "^4.16.2"
  }
}

Levantando un servidor

El siguiente paso será montar un servidor usando NodeJS + Express, para lo cual, tendremos que crear un nuevo archivo llamado server.js  directamente sobre la raíz del proyecto, el cual se verá de la siguiente manera:

var express = require('express')
var http = require('http')
var app = express()

app.get('/', (req, res) => {
  res.status(200).send("Welcome to API REST")
})

http.createServer(app).listen(8001, () => {
  console.log('Server started at http://localhost:8001');
});

Con estas simples líneas, hemos creado un servidor web capaz de servir peticiones web, sobre el cual montaremos nuestra API REST. Antes de ejecutar este código, vamos a analizar qué está pasando. Lo primero que podemos apreciar, es que importamos el módulo Express del que ya hablamos y el módulo Http, el cual es parte del estándar NodeJS, por lo que hace falta instalarlo con NPM. Este segundo módulo es utiliza para crear oyentes capases de escuchar peticiones HTTP en un determinado puerto. El segundo paso será crear una instancia de Express, como podemos observar en la línea 3.

Una vez hechos con la instancia de Express, solo nos resta crear los Routers, los cuales son las reglas por medio de las cuales Express sabrá como procesar las diferentes peticiones en diferentes URL’s, para lo cual, Express proporcionar una serie de funciones para procesar los diferentes métodos que soporta HTTP, como es GET, POST, DELETE, PUT, etc. En este caso, hemos creado un router para atender las peticiones que lleguen a la raíz del servidor. Es por eso la importancia de la línea 5, la cual responderá con la frase “Welcome to API REST” al recibir una petición GET a la raíz del servidor.

Al igual que tenemos la función GET, tenemos todas las demás, por ejemplo, POST, DELETE, PUSH, PUT, etc. las cuales se definen de la misma forma que GET, pero solo es necesario cambiar la función con la del método HTTP deseado, por ejemplo: app.post(), app.delete(), app.push(), app.put(). Todas estas variantes, reciben dos parámetros, el primero es la URL en la cual responden y el segundo es una función (Callback) la cual será ejecutada una vez que una petición sea recibida.

Finalmente, y una vez que tenemos todas las reglas de routeo (routers), tendremos que crear un oyente para recibir las peticiones, para ello nos apoyamos del módulo Http como podemos ver en la línea 9. El server Http lo creamos (createServer) pasando como parámetro la instancia de Express para finalmente levantar el servidor con la función listener. Esta última, recibe el puerto en el que escucha y una callback que se ejecuta una vez levantado el server.

Probando el servidor

Una vez que tenemos una primera versión de nuestro servidor, solo nos queda probarla para asegurarnos de que todo funciona bien, por lo cual, regresamos la línea de comandos y ejecutamos node server.js , como resultado tendremos lo siguiente:

Una vez tenemos la confirmación de que nuestro server esta arriba, procedemos con probarlo con el navegador, por lo que entramos a la URL http://localhost:8001 y veremos el siguiente resultado:

Si ves esto, es porque nuestro servidor ya está listo. No es gran cosa, pero al menos ya es avance para construir nuestra API REST.

Ya con esto, tenemos todo preparado para iniciar con la construcción de nuestros servicios, pero esto lo dejaremos para la segunda parte de este artículo.

Continuación (Segunda parte)

The post Como construir un API REST con NodeJS (Primera parte) appeared first on Oscar Blancarte - Software Architecture.