json-server es una herramienta NodeJS que nos permite prototipar o mockear un API REST de forma muy rápida. Ya sea para empezar un desarrollo Frontend si esperar al desarrollo del BackEnd o porqué necesitamos mockear el BackEnd por el motivo que sea.

Una vez definido el API a usar es muy rápido y sencillo usar cualquier petición HTTP con los métodos GET, POST, PUT, PATCH, DELETE …

Caracteristicas

• Creación rápida de API REST
• Basado en un archivo JSON
• Funcionalidades RESTful básicas
• Paginación, filtros, ordenación
• Soporte para relaciones (anidamiento)
• Observación de cambios en el archivo (hot reloading)
• Middleware personalizado
• Rutas personalizadas
• Generación de datos aleatorios (Faker.js)
• No requiere base de datos

Ventajas

1. Permite prototipar APIs en minutos sin necesidad de una base de datos real ni lógica de servidor compleja. Ideal para pruebas y desarrollo frontend.
2. Facilita la edición y gestión de los datos directamente en un archivo JSON simple. No se requiere conocimiento de bases de datos.
3. Soporta métodos HTTP comunes (GET, POST, PUT, PATCH, DELETE) para manipular los recursos.
4. Permite simular consultas de datos realistas con parámetros de URL para paginación, filtrado y ordenación.
5. Permite simular relaciones entre recursos a través de la anidación en el archivo JSON o utilizando la convención _embed.
6. Detecta automáticamente los cambios en el archivo JSON y actualiza la API sin reiniciar el servidor.
7. Permite extender la funcionalidad con middlewares de Express.js para añadir lógica personalizada (ej. validación básica).
8. Posibilidad de definir rutas personalizadas para casos de uso específicos que no encajan en el modelo RESTful estándar.
9. Puede integrarse con librerías como Faker.js para generar datos de prueba realistas rápidamente.
10. Simplifica el entorno de desarrollo al eliminar la necesidad de configurar y gestionar una base de datos.

Incovenientes

1. No apto para producción debido a la falta de seguridad, escalabilidad y funcionalidades empresariales.
2. La complejidad del archivo JSON puede aumentar rápidamente con grandes volúmenes de datos, dificultando su mantenimiento.
3. Carece de funcionalidades avanzadas como transacciones, autenticación/autorización robusta, validación de esquemas complejas, etc.
4. Las capacidades de consulta son limitadas en comparación con una base de datos completa. No admite consultas complejas o joins.
5. Las relaciones complejas pueden volverse difíciles de manejar y mantener en el archivo JSON.
6. Puede haber un ligero retraso en la detección de cambios en archivos muy grandes.
7. Requiere conocimiento de Express.js. La creación de middlewares complejos puede anular la simplicidad inicial de JSON-Server.
8. La sobrecarga de rutas personalizadas puede complicar la configuración y el mantenimiento.
9. La configuración inicial para la generación de datos puede requerir un poco de código.
10. No permite persistencia de datos real entre sesiones o reinicios del servidor sin guardar el archivo JSON manualmente.

Instalar y crear un proyecto

Crear un proyecto node des1de cero:

mkdir projectName
cd projectName
npm init
package name: (json-server-demo)
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to C:\devel\source\proofOfConcept\json-server-demo\package.json:

{
  "name": "json-server-demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}


Is this OK? (yes) yes

Esto nos crea un ficheero package.json que describe la información del paquete npm (todo proyecto npm es en sí mismo un paquete npm).

Instalar json-server

Ahora hace falta instalar json-server y usuarlo, podemos instalarlo de forma global como una herramienta nodejs más o como una librería de nuestro proyecto (que quedaría en la subcarpeta node_modules):

• Global: npm install -g json-server
• Local: npm install json-server

En el primer caso podremos ejecutar el comando escribien “json-server” en cualquier ruta del equipo donde node esté en el PATH. Para el segundo caso necesitamos usar el comando npx de node y hay que ejecutarlo en la carpeta raíz del proyecto que hemos creado y donde lo hemos instalado. Así:

npx json-server (pero aun no lo vamos a ejecutar!)

Configurar los datos y las rutas

Necesitamos un fichero donde estén los documentos JSON que van a devolver los endpoint REST que queremos mockear. Para ello, creamos un fichero db.json con “base de datos” de los ficheros JSON de cada endpoint, como esta:

{
  "posts": [
    { "id": "1", "title": "a title", "views": 100 },
    { "id": "2", "title": "another title", "views": 200 }
  ],
  "comments": [
    { "id": "1", "text": "a comment about post 1", "postId": "1" },
    { "id": "2", "text": "another comment about post 1", "postId": "1" }
  ],
  "profile": {
    "name": "typicode"
  }
}

Ahora ya podriamos arrancar la aplicación con el comando:

npx json-server -h 0.0.0.0 -p 8080 db.json
JSON Server started on PORT :8080
Press CTRL-C to stop
Watching db.json...

♡( ◡‿◡ )

Index:
http://localhost:8080/

Static files:
Serving ./public directory if it exists

Endpoints:
http://0.0.0.0:8080/posts
http://0.0.0.0:8080/comments
http://0.0.0.0:8080/profile

Aquí vemos que el programa detecta las 3 entradas que hemos creado con sus colecciones y nos indica los endpoints disponibles que ya se pueden usar con cURL, xHTTPRequest, etc. En Web tambien funciona:

Tendremos disponibles las operaciones habituales REST:

GET /posts
GET /posts/1
POST /posts
PUT /posts/1
DELETE /posts/1
GET /comments
GET /comments/1

En versiones anteriores (la actual es la 1.0.0-beta.3) se podia crear un fichero routes.json donde se mapeaban endpoints externos con las rutas del fichero. Por ejemplo si en realidad un API es /v1/blog/entradas y en el fichero es /posts configurar esa relación de forma que hacemos peticiones a /v1/blog/entradas y resuelve con los objetos de /posts.

Un ejemplo más claro sería algo así:

{
  "/api/posts": "/posts",
  "/api/comments": "/comments",
  "/blog/:resource/:id/show": "/:resource/:id"
}

En el último caso, tenemos unas URLS que dependiendo del :resource: accede a una sección u otra del fichero. Actualmente está en desuso. Para usarlo hay que instalar una versión anterior de json-server (en node con @version le indicamos a npm una version concreta):

npm install -g json-server@0.17.4

Añadir un middleware

Actualmente también está en desuso. Debemos usar una versión anterior a la 1.x.

Para ampliar todas estas funcionalidades podemos crear nuestro programa node (index.js) y que implemente un json-server (basado en Express) y detallar programáticamente su comportamiento.

En este caso se ejecutará como node index.js o npm start si actualizamos package.json (más abajo la versión modificada).

Un fichero ejemplo:

// server.js
const jsonServer = require('json-server')
const server = jsonServer.create()
const router = jsonServer.router('db.json')
const middlewares = jsonServer.defaults()

server.use(middlewares)

// Add custom middleware before JSON Server router
server.use((req, res, next) => {
  console.log('Time:', Date.now())
  next()
})

server.use(router)
server.listen(3000, () => {
  console.log('JSON Server is running')
})

Referencias

1. json-server
2. package-json
3. ExpressJS