core-mock-api
v0.0.2
Published
<h1 align="center">Welcome to core-mock-api 👋</h1>
Downloads
3
Readme
Base Mock API for developers to be able to test REST services
🏠 Homepage
Prerequisites
- node >=18 <19
Install
yarn install
Run linting
yarn lint
Run tests
yarn test
Run typechecks
yarn tsc
Usage
Development
yarn dev
app accessible at localhost:8080
We are based on JSON Server, https://github.com/typicode/json-server
Data and server config is stored in src/db.json
. If you make POST, PUT, PATCH or DELETE requests, changes will be automatically and safely saved to db.json using lowdb.
Id values are not mutable. Any id value in the body of your PUT or PATCH request will be ignored. Only a value set in a POST request will be respected, but only if not already taken.
Server supports these HTTP Methods:
GET /posts
GET /posts/1
POST /posts
PUT /posts/1
PATCH /posts/1
DELETE /posts/1
Filter
Use . to access deep properties
GET /posts?title=json-server&author=typicode
GET /posts?id=1&id=2
GET /comments?author.name=typicode
Paginate
Use _page and optionally _limit to paginate returned data.
In the Link header you'll get first, prev, next and last links.
GET /posts?_page=7
GET /posts?_page=7&_limit=20
10 items are returned by default
Sort
Add _sort and _order (ascending order by default)
GET /posts?_sort=views&_order=asc
GET /posts/1/comments?_sort=votes&_order=asc
For multiple fields, use the following format:
GET /posts?_sort=user,views&_order=desc,asc
Data generation
yarn generate:data
will generate data
to src/db.json
from config.json
. Config definition looks like this:
{
...
"<endpoint>": {
"config": {
// config of properties returnd and managed by endpoint
"<property_name>": type
},
"size": number,
"data": [
// you can pass specific data based on endpoint config
]
}
}
- config
- config of properties returnd and managed by endpoint
- supported types:
- "id" - default identificator
- we support Faker https://fakerjs.dev/ so any API options is valid to pass, eg
"commerce.product"
- size - size of generated collection, by
default
10 - data - you can pass specific data based on endpoint config, data are merged with generated data
example:
{
...
"products": {
"config": {
"id": "id",
"title": "commerce.product",
"description": "commerce.productDescription",
},
"size": 100,
"data": [
{ "id": 1, "title": "Product number 1", "description": "Some description" },
{ "id": 2, "title": "Product number 2", "description": "Some description" },
{ "id": 3, "title": "Product number 3", "description": "Some description" }
]
},
...
}
Nested routing
JSON Server
automatically resolves nested routing when proper id
and parent id <endpoint>Id
are provided.
"comments": {
"config": {
"id": "id",
"postId": "relation.posts.id",
},
}
postId
has
Advanced endpoint mocking
JSON Server
does not support composed routes so you could MOCK these by use of customRouter.ts
or by configuring your own router.
import express from 'express';
const router = express.Router();
router.use('/api/admin/about', (req, res) => {
res.json({
message: 'example of composed routes which could not be handled by JSON server'
});
});
export const customRouter = router;
Advanced endpoint with custom statuses and errors
when in need to test specific statuses mainly for error handling, those can be added to config under specific section __errors__
{
"posts": {
"data": [
{ "id": 1, "title": "Post number 1", "description": "Some description" },
{ "id": 2, "title": "Post number 2", "description": "Some description" },
{ "id": 3, "title": "Post number 3", "description": "Some description" },
{ "id": 4, "title": "Post number 4", "description": "Some description" },
{ "id": 5, "title": "Post number 5", "description": "Some description" }
]
},
...
"__errors__": {
"validate": {
"status": 400,
"error": {
"message": "Validation failed"
}
},
"custom": {
"status": 403,
"method": "post",
"error": {
"message": "Custom Forbidden"
}
}
}
}
Production build
yarn build
Production run
yarn start
app accessible at localhost:8080
CLI use (nodejs binary)
example running API server in apiMocks
folder and config in configError1.json
➜ apiMocks npx @e1011/mock-api@latest ./configError1.json
Need to install the following packages:
@e1011/[email protected]
Ok to proceed? (y) y
MM MM kk AAA PPPPPP IIIII SSSSS
MMM MMM oooo cccc kk kk AAAAA PP PP III SS eee rr rr vv vv eee rr rr
MM MM MM oo oo cc kkkkk AA AA PPPPPP III SSSSS ee e rrr r vv vv ee e rrr r
MM MM oo oo cc kk kk AAAAAAA PP III SS eeeee rr vvv eeeee rr
MM MM oooo ccccc kk kk AA AA PP IIIII SSSSS eeeee rr v eeeee rr
Mock API server, v0.0.24
Mock Api Lib is Installed
Mock API express app running at 8080
Static server
npx @e1011/mock-api@latest ./configError1.json ./folderWithStaticFiles
Custom port
pass as 3rd argument, will affect both api and static, so that localhost:[port]/api
serves all endpoints from config, and localhost:[port]/static
serves the static folder
npx @e1011/mock-api@latest ./configError1.json ./folderWithStaticFiles 4200
Docker use
build
yarn docker:build
run
yarn docker:run
app accessible at localhost:8080