api-mockr
Just another API mocker that can be configured to response random and specific data. It can help testing integrations with third parties. It's specially useful to create integration tests where we need to interact with an external service, so we can customize the response for different services exactly as we expect the external service responses.
Currently, only REST API responses are supported.
Demo
There is a demo available here. The application is deployed in the free tier of Cyclic, so please, don't abuse.
Getting started
This is a NodeJS application, you can install it as dev dependency in your project or as independent project, there is also a Docker Image.
Installation
Installation as dev dependency:
npm install --save-dev api-mockr
Installation as docker image:
docker pull dvlprtech/api-mockr
For further details about the use with docker you can access to DockerHub api-mockr image page.
How to use
You can use the CLI tool api-mockr
to start the application:
npx api-mockr
The following output will apear:
[🟢 api-mockr v0.0.0] Server running at: http://0.0.0.0:3003
There are several options params that can be used to configure the server:
-
--port
: The port to listen to. Default is3003
. -
--host
: The host to listen to. Default is0.0.0.0
. -
--silent
: If present, the server will not output any message. By default, the server will print every request with the basic info about the response. -
--verbose
: If present, the server will print every request with its params and payload and the applied server configuration when the server is created. -
--config
: The path to the config file. It's a multivalue param. -
--apiPrefix
: The prefix to invoque the API services. Default is/
. If set all mocked routes should be invoked with this prefix. I.e. The configured route/v1/users
should be invoked as/api/v1/users
if we use--apiPrefix=/api
.
Example of use:
$ npx api-mockr --port=13003 --host=localhost --apiPrefix=/api
[🟢 api-mockr v0.0.0] Server running at: http://localhost:13003/api
Without additional configuration, the default server will response with the following data to whatever request:
$ curl 'http://localhost:3003/api/whatever?foo=bar'
{"success":true,"request":{"path":"/api/whatever","params":{"foo":"bar"}}}
There is an exception, the call to /
will return a fixed text, that can be used to "ping" the server.
$ curl 'http://localhost:3003/'
API Mockr (v0.0.0)
Special params
There are some special params that can be used with each request:
-
_pretty
: If it's set totrue
, the response will be pretty printed. -
_delay
: The delay in milliseconds to wait before responding. By default 0. -
_forceError
: If it's set totrue
, the response will be an error with a http status code of500
by default. -
_clonePayload
: If it's set totrue
, the response payload will be a clone of the request payload but appling variable substitution if they are used in request payload.
The error response can be customized with 2 header:
-
x-mocker-force-error'
: HTTP status code to be returned, can be any value between400
and599
. Values out of range will be ignored. -
x-mocker-error-msg
: The error message to be returned, you can use variables in the message, like"ERROR: ${random.emoji} ${random.phrase}"
.
Example of error response:
$ curl 'http://localhost:3003/api/whatever?foo=bar&_forceError=true&_pretty=1'
{
"success": false,
"error": "Error in request to path: /api/whatever",
"request": {
"body": null,
"params": {
"foo": "bar",
"_forceError": "true",
"_pretty": "1"
}
}
}
Customizing the message and code:
$ curl -H "x-mocker-force-error: 418" -H 'x-mocker-error-msg: ERROR: ${random.emoji} ${random.phrase}' 'http://localhost:3003/api/whatever?foo=bar&_forceError=true&_pretty=1'
{
"success": false,
"error": "ERROR: 🐭 You cant quantify the driver without transmitting the multi-byte SQL microchip!",
"request": {
"body": null,
"params": {
"foo": "bar",
"_forceError": "true",
"_pretty": "1"
}
}
The emoji and the error phrase will be different with each call.
Server configuration
The config files can be read in YAML and JSON formats, the default config file is like this:
defaultResponse:
success: true
timestamp: ${server.isoDatetime}
request:
path: ${request.path}
body: ${request.payload}
params: ${request.params}
errorResponse:
$httpStatus$: 500
success: false
error: "${error}"
request:
body: ${request.payload}
params: ${request.params}
routes:
get:
"say-whatever":
success: true
author: ${random.personFirstName}
phrase: ${random.phrase}
There are 3 main sections in the config file:
-
defaultResponse
: The default response to be returned when there is no match for the request path and the configured routes -
errorResponse
: The error response payload to be returned when an error occurs. -
routes
: The routes to be mocked grouped by HTTP method (get, post, put, ...). A wildcard (*
) can be used to match any method and/or any path.
Variables in configuration
We can use variables in the configuration files to provide dynamic values with every response. There are several variables types:
-
random
: Random values for all sort of data. i.e.random.personFullName
,random.integer
,random.department
, ... -
request
: Values from the request. i.e.request.path
,request.params
,request.payload
-
server
: Values from the server. i.e.server.timestamp
,server.isoDate
, ... - Path variables: Variables created in the config file to refer a path section. i.e. A configured route like
/api/users/${username}
will create a variableusername
with value "bob23" for a request path like/api/users/bob23
, this variable can be used in the route response (... "author": "${username}", ...
).
Some of the variables accept parameters, the params should be added after a dot (variable.paramValue
) for example:
-
request.params.foo
: In requests like/api/whatever?foo=bar
It will returnbar
. -
random.personFirstName.male
: This params acceptsmale
orfemale
as possible input values -
random.choose.monday.sunday.tuesday
: This params accepts a variable number of params and It will return one of them randomly.
For further informaton about the supported variables, please refer to the VARS.md file.
There are several examples of config files in examples directory.