Mock-API

An easy and configurable mock server.

Features

• [x] A fake REST API data server :smiley:
• [x] Acts as proxy server. Can forward request and fetch data from other data services :relieved:

Points

1. Helps in POST request to your server from anywhere, even from localhost
2. Fixes CORS issue.
3. We can make request to authenticated API.

Install

npm i --save-dev @rnmkeshav/mock-api

Setup

Step 1:

To run mock-api you will need a config file. This can be created with running below command in terminal

npx mock-api-setup

Step 2:

Run following command from terminal to start mock-api server

npx mock-api

Add npm script in your package.json file.

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "mock-api": "mock-api"
}

Run following command from terminal to start mock-api

npm run mock-api

Testing

Open browser and hit

• Test 1:

http://localhost:3002/photos/1

The above URL fetches data from https://jsonplaceholder.typicode.com API server which is default configured in your mock-api.config.js file. All the request will goto default server until it is overriden by custom route.

• Test 2:

http://localhost:3002/search/users

The above URL fetches data from https://api.github.com/ which is mentioned in custom routes of mock-api.config.js file.

How mock-api works

This package usage express to create a proxy server. It takes your request, checks request method and url passes it through some middleware. It is these middleware which calls route.beforeRequest before making request and pick route.payload(more on this later) to make api call to your service. Middleware also puts response from your service(provided hostname in config/route) to routes.response_data and calls routes.beforeResponse() before sending response back to client. Middleware usage config file to create and manipulate request/response.

config file details

To run mock-api, config(mock-api.config.js) file is mandatory. This config file gets created by running npx mock-api-setup but can also be created manually. This is plain javascript file which exports an object.

You will be manipulating this file to achieve all your desired result and fake/forward api responses.

#mock-api.config.js

let config = {
  port: 3002,
  forward: {
    hostname: "https://jsonplaceholder.typicode.com", // hostname where request will be forwarded. This will be fallback for custom route.
    headers: { // headers to be sent in all requests.
      cookie: "pelUUID=96d2cfa0-e0ce-4795-beb3-917c5c1dd79c; _ga=GA1.2.1683668930.1598687051; _gcl_au=1.1.1869798560.1598687054; _fbp=fb.1.1598706524131.962812492;hl=en; pelUUID=174edf11de59da-068985a51643be-5b7f7327-5294d-174edf11de690c; __cfruid=e14408ee99e3a9ae0b2b1bcdfe71dda5c137e3a4-1601719873; WZRK_G=9746059b128d44d1bc23bec757dfb5c3; _gat=1; _gat_fabric=1; WZRK_S_8W6-695-WK5Z=%7B%22p%22%3A9%2C%22s%22%3A1601719832%2C%22t%22%3A1601720622%7D; modal_login=true", // cookie you would like to send as header when making request to your server(mentioned in hostname)
      host: "jsonplaceholder.typicode.com",
      accept: "application/json",
      referer: "https://jsonplaceholder.typicode.com/",
      "accept-encoding": "gzip"
    }
  },
  routes: [{  // custom routes if you want to modify request payload or response data. This can also be used to override request/response default data(headers/status) mentioned above in `config.forward`
    enable_forward: true, // true means request would be forwarded to routes.request.hostname if mentioned otherwise fallback to config.forward.hostname. false means api would be returning route.response.response_data
    request: {  // request object details. 
      path: "/search/users",  // route path for which this object will come into force.
      method: "GET",
      headers: {  // This will override config.forward.headers
        Host: "api.github.com"
      },
      hostname:"https://api.github.com/", // This will override config.forward.hostname
      query: {
        q: "rnmkeshav"
      },
      payload: {},  // Payload to send to server for this API call
      beforeRequest: function ({params, body}) {
        // This gets called before network request
        // This method can change request object.
      }
    },
    response: {
      headers: {  // Can be used to override response header.
        "custom_response_header": "custom_response_header_value"
      },
      status: "", // Can be used to override response status code
      response_data: {},  // This is where response data is placed when API call succeeds.
      beforeResponse: function () {
        // This method gets called after network request
        // This method can change response object
      }
    }
  }, {  // To see this in action, make a POST request to `http://localhost:3002/api/users` with {"name":"morpheus","job":"leader"} as request payload 
    enable_forward: true, 
    request: {
      path: "/api/users",
      method: "POST",
      hostname: "https://reqres.in/",
      payload: {},
      headers: {
        skip_req_headers: true, //headers which gets sent automatically from client/browser
        skip_forward_all_headers: true, //headers which gets sent in forward all request. `config.forward.headers`
        // host: "https://reqres.in",
        accept: "application/json",
        // referer: "https://reqres.in/",
        // "accept-encoding": "gzip",
        // 'Content-type': "application/json"
      }
    }
  }]
}

module.exports = config;

Config object detail

This is the main object which gets exported from mock-api.config.js

In this document, this object is also referred as config object

Property | Type | Details | Default -------- | ------- | ------- | ------- port | Number | Port on which mock-api server runs. | 3002 forward | Object | An object which contain details about request where data will be forwarded. Details of this object can be found below. | { } routes | Array | An array which holds detail of each route where you want to do some manipulation in request or response object. | [ ]

Forward object details

An object which help build request object to send to different service. This is forward all object. All the route coming to mock-api server will be getting forwarded according to this object rule.

In this document this object is also referred as config.forward object

Property | Type | Details | Default ------- | ------- | -------- | -------- hostname | String | hostname of the url where you want to forward all your request to. | "https://jsonplaceholder.typicode.com/" headers | Object | An object which contains any headers data you want to send in your request. This can be used to send cookie to an authentication protected API | { }

route object details

This makes custom route request. route property of config(mock-api.config.js) is an array of object which contains individual route details. An object which you can use to let mock-api know you want to perform some manipulation with request or response data.

In this document this object is also referred as config.route object

Property | Type | Details | Default ------- | ------- | ------- | ------- enable_forward | Boolean | This flag tells mock-api that should it forward the request for mentioned path or not. If false, the request to this route will return response with specified headers, status and response_data. | false request | Object | This object tells request details which will be used for request.path url. We can use this object to modify POST payload, query params, headers sent to service etc. | { }
response | Object | This object tells response details which will be used for request.path url. We can use this object to modify response data, response headers, status codes etc. | { }

Route's request object

By default all request adheres config.forward object to construct request's hostname, headers etc. This object overrides default behavior and tells mock-api to use this object to construct a custom request object for mentioned path.

In this document this object is also referred as config.route.request object

Property | Type | Details | Default ------- | ------- | ------- | ------- path | String | A url path for which you want to manipulate your request or response and create a custom request. Same as express.js path | "" method | String | Method for custom request's path | GET headers | Object | Header object which will be sent when you make request to this custom request's path | config.forward.headers hostname | String | Hostname for custom request. This when specified overrides config.forward.hostname | undefined payload | Object | This object gets merged with your client's(browser) POST request's body to construct final payload and sent to mentioned path in custom request. | { } query | Object | Query param to send with request | { } beforeRequest | Function | A function which has access to current route object(config.route.request) using this and gets called before sending request to your path in custom request. This function also provides access to route's request params and request's payload body | noop

Route's response object

This object is used to manipulate response for custom route of path mentioned config.route.request

In this document this object is also referred as config.route.request object

Property | Type | Details | Default ------- | ------- | ------- | ------- headers | Object | This is used to manipulate response headers. This object merges and overrides response headers coming from service/API | { } status | Number | Overrides response's status code | "" response_data | Object | Response data you want from this request. This object gets populated as soon as mock-api gets response from your custom request server. | { } beforeResponse | Function | A callback function which gets called after mock-api gets response from your custom request. This function gets called after populating data in response_data with parameters as request's params and body. | noop

Route's request header object

We can send specific headers for each different route with this object. We can also use this object to override headers sent from browser automatically.

Header priority: Request Headers < Forward All headers < Custom headers

  let headers = Object.assign({}, req_headers, config_headers, custom_headers);

Header group | code_variable_name | Description ------ | ------ | ------ Request Headers | req_headers | The headers which gets sent from client/browser while making request to mock-api server. Forward All headers | config_headers | The headers which gets sent from config file to all requests which match forward route of config object. This is same as config.forward.headers Custom headers | custom_headers | This is the header object which you write for each specific route. This is same as config.route.request.headers object. This object has highest priority for individua route.

Customising route's request header object

There are times when we want to skip headers from certain group like Request Headers or Forward All headers etc. You can use the following header keys in custom request's header to skip the group.

Example 1: You don't want to send headers client/broswer is sending to be forwarded to your request server.

Example 2: When you have customised a route which matches the config.forward object but you don't want to send headers mentioned in config.forward.headers object

Header Key | Description | Type | Default ------ | ------ | ------ | ------ skip_req_headers | This will skip headers sent from client/browser. No headers from client/browser will be sent to request server | Boolean | false skip_forward_all_headers | This will skip headers sent from config.forward.headers object. The header from client/browser will still to to request server. | Boolean | false

If you want to send only the header defined for route in config.route.request.headers then make both skip_req_headers and skip_forward_all_headers as true

Examples

Example 1

Example 2

For Developers

Method 1

• Install mock-api in your existing repository with following command

npm install --save-dev https://github.com/rnmKeshav/mock-api/tree/{your_branch_name}

• Add script in package.json to run mock-api

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "mock-api": "mock-api",
  "mock-api-setup": "mock-api-setup"
},

• Run setup script

npm run mock-api-setup

• Run mock-api server

npm run mock-api

Method 2

• Step 1:

Clone this repo

• Step 2:

Navigate to mock-api/examples/custom folder

• Step 3

Run npm run mock-api in terminal

• Step 4

Run mock-api/examples/custom/index.html with live server to make requests.