Using JSON Server for demos and prototypes
I build a lot of demos and prototypes. I often have the need to build a back-end API service quickly for these examples. To do this I use JSON server. JSON Server allows me to create a functional REST-ful API without writing any code.
Installing JSON Server
Let’s take a quick look how it works, starting with installing JSON Server. JSON Server is available as a NPM package and can be installed globally. We can use
npm to install it.
-g intalls JSON Server as a globally available binary:
Configuring JSON Server
The JSON Server is configured using a JSON file in which uses a DSL to define API endpoints. We define each endpoint we want to be able to query, together with some sample data.
Let’s look at an example.
This JSON defines three endpoints and some associated data for each. The first endpoint,
warehouses, is a list of warehouse records by
location. We’ve defined two warehouses:
OR. The second endpoint,
users, returns records with
lastName fields. A fourth field,
warehouseId, is a reference to the
id field in the
warehouses endpoint, linking the two data sets. The third endpoint,
items, returns items with the
cost fields. Each record also has a reference using the
warehouseId field to our previous
Let’s add this JSON to a file, we’ll call it
api.json, and run JSON Server.
Starting the JSON Server
We run the
json-server binary and pass in our
api.json file as a command line argument to execute it.
--watchflag tells JSON Server to watch the
api.jsonfile for changes and to refresh the server when it changes.
We can now browse to
http://localhost:3000/users/ and we’ll get a JSON response to our
GET request containing all of the records from the
users endpoint. We can also access individual records via their ID, browsing to
http://localhost:3000/users/1 will return the first
users record in our
The server also supports query parameters, for example
http://localhost:3000/users?firstName=Amala, will return all of the
users records with a
firstName field of
You can also refer to linked records, for example to return all of the users associated with the
OR warehouse we would query:
http://localhost:3000/warehouses/2/users. Or to return all the items in the
There’s also a wide variety of other querying mechanisms using filters, pagination, slicing, operators, sorting and even full text search.
You’re also not limited to purely
GET requests and can add data to our data sets.
To add data (or delete it) we can use
DELETE requests to your API. This functionality uses lowdb, a Lodash-powered JSON database, to update your
api.json file with new records.
POST a new user record.
POST a new record to the
/users endpoint. We’ve specified a
Content-Type header of
application/json, which is required to ensure the API knows our incoming request is JSON. We’ve then specified a JSON snippet that adds a new user record in the
idvalues are not mutable. Any
idvalue in the body of a
PATCHrequest will be ignored. Only an
idvalue set in a
POSTrequest will be honored, but only if the
idvalue is not already taken.
Now if you go to
http://localhost:3000/users/4, you’ll get:
JSON Server has a bunch of other useful functions: you can add alias and additional routes, load schema’s from remote sources, add SSL, middleware, add static content, or use JSON Server itself in a Node app. It’s a useful addition to your toolkit if you need a quick and easy demo API.