Mock Server
Define Mock API

Mock Server API Definition

The Mock Server API is modelled on ExpressJS and Sinatra. If you are familiar with either of these frameworks you will know that they provide a clean, simple model for working with HTTP requests and responses.


mock.define(path, method, callback)

The mock.define() method configures HTTP routes. The following snippet illustrates the simplest route definition possible. Mock Server translates the path strings to regular expressions, used internally to match incoming requests. Query strings are not considered when performing these matches, for example "GET /" would match the following route, as would "GET /?user=bob".

mock.define("/", "GET", function(req, res) {
  res.send("Hello world");

The callback is always passed a Request object and a Response object. Route parameters can be specified using {param_name} in paths. For example, if you have a route /user/{name}, then the "name" property is available to you as

mock.define("/user/{name}", "get", function(req, res) {
  res.send("Hello " + req.params["name"]);

Its important to note that all mock.define() blocks must end with a call to send a response such as res.send(). Without this call your service will timeout and not return a successful result. See the Response section for more details.


The req object represents the request message and has properties for the request query string, parameters, body, HTTP headers, and so on. In this documentation and by convention, the object is always referred to as req (and the response message is res) but its actual name is determined by the parameters to the callback function in which you’re working.



This property is an array containing property names mapped to named route "parameters", defaults to {}. For example, if you have a route /user/{name} then the "name" property is available to you at

// GET /user/bob
// = "bob"


This property is an object containing the parsed query string, defaults to {}.

// GET /user?name=bob
// = "bob"
// GET /track?id=8efd&parcel[speed]=express
// = 8efd
// = express


This property is an object containing the parsed request body, defaults to {}. The body will be parsed based on the "Content-Type" header.

// POST {"name": "bob"}
// = "bob"


This property is an object that contains the parsed cookies sent by the user-agent

// Cookie: name=bob
// = "bob"


This property returns the original request URL.

// GET /user?name=bob
// = "/user?name=bob"


This property returns the request URL pathname

// = "/user"


This property is an array of Accepted media types.

    [ { value: 'application/json',
    quality: 1,
    type: 'application',
    subtype: 'json'},
    { value: 'text/xml',
    quality: 0.5,
    type: 'text',
    subtype: 'xml' } ]


This property returns the originating IP address of the request

    // = ""



This function returns the case-insensitive request header for field.

// = "application/json"
// = "application/json"

Check if the incoming request matches the given mime type. If "Content-Type" header field isn't present on the request, it will return false

// with Content-Type: text/html'html');'text/html');'text/*');
// = true'json')
// = false 


The res object represents the response message that Mock Server sends in response to a request message. Use the res object to set response heaers, status codes and more. In this documentation and by convention, the object is always referred to as res (and the request message is req) but its actual name is determined by the parameters to the callback function in which you’re working.



Sets the response status. If you dont set a status, a successful result will default to a 200 status


res.set(field, [value])

Sets a response header. Sets header field to value where value is a string or an Array of strings. Alternatively, pass in a single argument of type object

res.set('Content-Type', 'application/json');
res.set('X-Header', ['abc', '123']);
'Content-Type': 'application/json',
'Content-Length: '123'


Gets the case-insensitive response header for field.

// = "application/json"
// = "application/json"


Sets the Content-Type to the mime lookup of type.


res.send([body|status], [body])

Sends a response.

res.send({ name: 'bob' });
res.send('some text');
res.send(404, 'Sorry, cant find that route');
res.send(500, { error: 'Gone pearshaped' });

If a Content-Type hasnt been set this function will parse the data and set the appropriate header. For example, if you pass in an object then the Content-Type will be set to 'application/json'. When a String is provided the Content-Type is set to 'text/html'. When a Number is provided without a body then a response body string is assigned for you. For example, 200 will respond with the text 'OK'.

Calling this function will also complete execution of your service. Further calls to functions will have no effect.


Sends a json response. This method is identical to res.send() when an object or array is passed however it will also convert non-objects, such as null, into JSON representation.

res.json({ name: 'bob' });
res.json(404, { error: 'Not found' });

res.render(template, [locals])

Renders the response using a Liquid template and sends the rendered result. The template parameter must correspond to a template files in the applications /templates directory without the file extension. For example, /templates/users.liquid template is referenced by its name 'users':

res.render('users', { name: 'bob' });

Locals can be passed in and must be an Object or Array. These are then made available to the template as res.locals. In the above example, 'name' would be available at