Creando una Web API con Node.js y Express

Una Web API nos permite exponer funcionalidad de una aplicación a través del protocolo HTTP. En este tutorial vamos a crear una Web API utilizando Node.js y una librería llamada Express.

Para seguir este tutorial vas a necesitar lo siguiente:

• Estar familiarizado con JavaScript y Node.js. Si no lo estás te recomiendo el siguiente post: Introducción a Node.js.
• Estar familiarizado con la línea de comandos. Si no lo estás te recomiendo el siguiente post: La línea de comandos.
• Tener instalado Node.js en tu computador. Si no lo tienes puedes seguir estas instrucciones.
• Tener instalado un editor de texto como VSCode, Atom o uno similar.
• Estar familiarizado con el protocolo HTTP. Si no lo estás te recomiendo el siguiente post: El protocolo HTTP.

Un API (por sus siglas en Ingles Application Programming Interface) es, en general, una forma en que un software interactúa con otro software. Una Web API es un tipo de API que utiliza el protocolo HTTP como forma de comunicación utilizando algún formato de intercambio de información como XML o JSON.

El servicio que vamos a crear le va a permitir a otras aplicaciones publicar, editar, eliminar y listar frases célebres. Cada frase célebre va a estar compuesta de un texto y un autor. Por ejemplo:

• Texto: No hay caminos para la paz; la paz es el camino.
• Autor: Mahatma Gandhi

JSON (JavaScript Object Notation)

Para nuestra API vamos a utilizar JSON como formato de intercambio de información. JSON es un formato que es fácil de interpretar por una aplicación y al mismo tiempo legible por un humano.

Veamos un ejemplo de JSON en el que estamos representando un vuelo:

{
  "airline": "Oceanic",
  "status": "crashed",
  "departure": {
    "iata": "SYD",
    "time": "2004-09-22 14:55"
  }
}

JSON es parecido a un objeto de JavaScript pero con algunas diferencias importantes:

1. Los nombres de las propiedades deben estar entre comillas.
2. Los valores pueden ser de los siguientes tipos únicamente: String, Number, Boolean, Array, JSON Object.

Configurando el proyecto

Abre una línea de comandos y crea una carpeta para el proyecto:

mkdir quotes

Ingresa a la carpeta e inicializa el proyecto ejecutando los siguientes comandos:

cd quotes
npm init -y

Ahora instala Express con el siguiente comando:

npm install express

Creando la primera ruta

Abre la carpeta del proyecto en tu editor de texto preferido (VSCode, Atom, etc.) y crea el archivo index.js con el siguiente contenido:

const express = require("express")
const app = express()

// nuestra primera ruta
app.get('/quotes', (req, res) => {
  res.json([
    { text: "Quote 1", author: "Author 1" },
    { text: "Quote 2", author: "Author 2"}
  ])
})

app.listen(3000, () => console.log("Servidor listo ..."))

Guarda el archivo y ejecútalo con el siguiente comando:

node index.js

Deberías ver el texto “Servidor listo …“. Abre un navegador en la dirección http://localhost:3000/quotes, deberías ver el JSON que estamos retornando de la ruta:

[{"text":"Quote 1","author":"Author 1"},{"text":"Quote 2","author":"Author 2"}]

Para detener el servidor oprime Ctrl + C.

Almacenando las frases

Aunque no vamos a guardar las frases en una base de datos, sí vamos a crear un módulo que nos almacene las frases en memoria. Crea un archivo quotes.js con el siguiente contenido:

const quotes = []
let nextId = 0

function list() {
  return quotes
}

function create(text, author) {
  const quote = { id: nextId, text, author }
  quotes.push(quote)
  nextId++

  return quote
}

module.exports = { list, create }

Ahora vamos a importarlo y utilizarlo desde index.js, que debería quedar de la siguiente forma:

const express = require("express")
const quotes = require("./quotes")

const app = express()

// nuestra primera ruta
app.get('/quotes', (req, res) => {
  res.json(quotes.list())
})

app.listen(3000, () => console.log("Servidor listo ..."))

Reinicia el servidor (lo detienes oprimiendo Ctrl + C y lo inicias con el comando node index.js) y refresca el navegador, deberías ver un arreglo vacío:

[]

La ruta para crear frases

Vamos ahora a crear la ruta que nos va a permitir crear las frases. Para eso debemos decirle a Express que vamos a recibir JSON de los clientes. Eso se hace con la siguiente línea:

app.use(express.json())

Y la ruta sería la siguiente. Fíjate que la ruta es la misma que la anterior, /quotes, pero cambia el método, ahora vamos a utilizar POST:

app.post('/quotes', (req, res) => {
  const { text, author } = req.body
  const quote = quotes.create(text, author)
  res.json(quote)
})

Unido con lo anterior el archivo index.js debería quedar de la siguiente forma:

const express = require("express")
const quotes = require("./quotes")

const app = express()
app.use(express.json())

// nuestra primera ruta
app.get('/quotes', (req, res) => {
  res.json(quotes.list())
})

// ruta para crear frases
app.post('/quotes', (req, res) => {
  const { text, author } = req.body
  const quote = quotes.create(text, author)
  res.json(quote)
})

app.listen(3000, () => console.log("Servidor listo ..."))

El método POST no se puede probar desde un navegador como hicimos con la ruta de listar, así que vamos a utilizar una herramienta llamada curl en la línea de comandos.

Inicia el servidor y abre otra pestaña en la línea de comandos para probar la nueva ruta:

curl -X POST -d '{ "text": "Quote 1", "author": "Author 1" }' http://localhost:3000/quotes

Crea varias rutas y revisa que la ruta de listar las muestre, puedes utilizar el siguiente comando:

curl http://localhost:3000/quotes

Nota: En vez de curl puedes utilizar una herramienta gráfica como Postman.

Las rutas para editar y eliminar

Para crear las rutas de editar y eliminar primero tenemos que modificar el archivo quotes.js para agregar los métodos de editar y eliminar:

const quotes = []
const nextId = 0

function list() {
  return quotes
}

function create(text, author) {
  // ...
}

// nuevas funciones
function edit(id, text, author) {
  const idx = quotes.findIndex(q => q.id === id)
  if (idx >= 0) {
    quotes[idx].text = text
    quotes[idx].author = author
  }
}

function destroy(id) {
  const idx = quotes.findIndex(q => q.id === id)
  if (idx >= 0) {
    arry.splice(idx, 1)
  }
}

module.exports = { list, create, edit, destroy }

Y ahora creamos las nuevas rutas en index.js:

// ...

app.patch('/quotes/:id', (req, res) => {
  const { text, author } = req.body
  quotes.edit(req.params.id, text, author)
  res.status(204).send()
})

app.delete('/quotes/:id', (req, res) => {
  quotes.destroy(req.params.id)
  res.status(204).send()
})

app.listen(3000, () => console.log("Servidor listo ..."))

Reinicia el servidor. Puedes utilizar los siguientes comandos para probar la ruta de crear, editar y eliminar frases respectivamente:

curl -X POST -H "Content-Type: application/json" -d '{ "text": "Quote 1", "author": "Author 1" }' http://localhost:3000/quotes
curl -X PATCH -H "Content-Type: application/json" -d '{ "text": "Quote 2", "author": "Author 2" }' http://localhost:3000/quotes/0
curl -X DELETE http://localhost:3000/quotes/0

Felicitaciones, has creado tu primera Web API! Puedes encontrar el código completo en este enlace.

¿Por qué RESTful API?

REST es una arquitectura que se utiliza para las Web API en donde se hace uso de la semántica del protocolo HTTP, es decir, los métodos, los códigos de respuesta y encabezados HTTP, entre otros. Además, las rutas se definen con un patrón muy estándar. Para nuestro ejemplo de frases (quotes) sería el siguiente:

• GET /quotes para listar.
• POST /quotes para crear.
• PATCH /quotes/:id para editar.
• DELETE /quotes/:id para eliminar.
• GET /quotes/:id para mostrar una frase específica.

En vez de quotes podría ser cualquier otro recurso como productos, facturas, empleados, etc.

Conclusión

En este tutorial vimos cómo crear y probar una RESTful API con Node.js y Express, que le permite a una aplicación exponer funcionalidad a otros clientes o aplicaciones. Los siguientes pasos serían:

• Agregar validaciones.
• Utilizar una base de datos como MongoDB en vez de guardar las frases en memoria.
• Implementar algún mecanismo de autenticación.
• Publicar el Web API en Internet utilizando un servicio como Heroku.
• Crear un front-end que consuma nuestro Web API y permita a las personas administrar las frases célebres a través de un navegador.

Si deseas aprender esto y mucho más de la mano de mentores experimentados te invito a que conozcas nuestro programa Full Stack JavaScript Web Developer.