Simple, Fast and Powerful file-based Node.js mock server
Mockiji is a generic Node.js REST API server.
Provided a JSON/HTML file, named along rules, it will create a REST route which will serve the file as the response.
Plus, you can also provide a JavaScript file to generate a response according to the request context.
Request: GET /api/of/mine
Response: HTTP 200 OK
{
"title": "The response to GET /api/of/mine (HTTP 200 OK)",
"description": "This filepath is /api/of/mine/get.json"
}
Request: POST /api/books/
Response: HTTP 503 Service Unavailable
{
"title": "This is a 503 HTTP Error to the request POST /api/books/",
"description": "This filepath is /api/books/post.503.json"
}
When Mockiji receives a request, it looks at the HTTP verb (GET
, POST
, etc.) and its path (/api/elem1/elem2
) before looking for a mock file matching it.
As an example:
The first file matching one of these patterns is served.
As you can see, Mockiji will try to match specific requests first,
then it will try to get more generic thanks to the @default
token
which may fit a folder name in the mocks folder hierarchy.
Mockiji contains some mocks to start playing with and help you understand how it works.
This first API is a library (the ones with books) where users kate and tom has borrowed some books.
Please install and launch Mockiji without editing the default configuration or the env.json
file and let's get started.
Start by loading http://localhost:8080/api-simple-library/users/tom/books
in your browser or REST Client (GET
verb).
These are the books borrowed by tom.
If you look at the Response Headers you will see a X-Mockiji-File
like this:
X-Mockiji-File: /srv/www/mockiji/mocks/api-simple-library/users/tom/books/get.json
It means the response content has been served from this file.
You can verify this by yourself by checking the content of this local file defined by X-Mockiji-File
.
If you replace "tom" by "alex" in the URL, you will receive another response.
X-Mockiji-File: /srv/www/mockiji/mocks/api-simple-library/users/@default/get_books.json
What is this @default
part in the path? It is a special token used by Mockiji.
Mockiji has tried to load a file with an "alex" in the path but he has not found any.
Then it tried to replace some parts from the URL with this special token @default
.
That's why this file has been served. Look at the file hierarchy in the api-simple-library
to understand.
Now we will request a non-existing request for this api.
Try this one: http://localhost:8080/api-simple-library/users/kate/comics
You should get a page looking like this one:
{
"errorCode": 404,
"errorDescription": "No mock file was found",
"evaluatedMockFilePaths": [
"/srv/www/mockiji/mocks/api-simple-library/users/kate/comics/get.*",
"/srv/www/mockiji/mocks/api-simple-library/users/kate/get_comics.*",
"/srv/www/mockiji/mocks/api-simple-library/users/get_kate_comics.*",
"/srv/www/mockiji/mocks/api-simple-library/get_users_kate_comics.*",
"/srv/www/mockiji/mocks/api-simple-library/users/kate/@default/get.*",
"/srv/www/mockiji/mocks/api-simple-library/users/@default/comics/get.*",
"/srv/www/mockiji/mocks/api-simple-library/@default/kate/comics/get.*",
"/srv/www/mockiji/mocks/@default/users/kate/comics/get.*",
"/srv/www/mockiji/mocks/api-simple-library/users/@default/get_comics.*",
"/srv/www/mockiji/mocks/api-simple-library/@default/kate/get_comics.*",
"/srv/www/mockiji/mocks/@default/users/kate/get_comics.*",
"/srv/www/mockiji/mocks/api-simple-library/@default/get_kate_comics.*",
"/srv/www/mockiji/mocks/@default/users/get_kate_comics.*",
"/srv/www/mockiji/mocks/@default/get_users_kate_comics.*"
]
}
No mock file was found and Mockiji tells you where it searched for mock files. This page is useful to understand why your mock file has not been found. You can also use theses paths to choose where to create your files for improving the API.
If you create one file and put it on one of these paths, you will be able to refresh your URL and see it served.
What happens if you create one JSON mock file but screwed up and put XML in it?
Try it by yourself you will get:
{
"error": "The mock file contains invalid JSON"
}
As usual, you can locate the served file with the X-Mockiji-File
response header and fix it with nice and valid JSON.
With Docker
Mockiji is not yet available on Docker hub, however you can build an image easily. You must have docker installed along with the `docker` command.From the app root folder:
docker build -t mockiji .
From the app root folder:
docker run -p 8080:8080 mockiji
Without Docker
You can use your favorite package manager and node process manager.You MUST have Node >= 6
and NPM >= 3
.
You MAY have yarn
and pm2
.
Please choose one of the following install option:
Install with yarn
From the `api/` folder: ```sh yarn ```Install with npm
From the `api/` folder: ```sh npm install ```Launch with pm2
From the `api/` folder: ```sh pm2 start processes.json ```Launch with Node
From the `api/` folder: ```sh node app ```You should now be able to load http://localhost:8080
in your browser or REST client now.
Mockiji always loads the following configuration file: api/config/default.json
.
You can edit this default file or override it (totally or partially) with a custom configuration file.
In this case, you have to point this custom configuration file into the api/config/env.json
file.
Example of env.json
file:
{
"name": "dev",
"path": "/srv/www/my-frontend-app/mocks/"
}
This file tells Mockiji to load a dev.json
file from the /srv/www/my-frontend-app/mocks/
folder.
Mockiji will throw an explicit error on boot if this custom configuration has not been found.
You will have to restart Mockiji if you want the configuration to change.
If you use pm2, you can do it with pm2 restart 0
(provided 0 is your mockiji pm2-process id)
Log files are located in the logs/
folder and can be configured in a configuration file (eg. api/config/default.json
).
If you use pm2, you can view them with pm2 logs 0
(provided 0 is your mockiji pm2-process id)
The configuration system is described in the Bunyan repository.
{
"name": "api-mockiji",
"filepath": "../logs/api-mockiji.log",
"level": "info",
"type": "rotating-file",
"period": "1d",
"count": 10
}