Documentation

Getting started

There are two basic ways of using Mocki - running it locally using the Mocki CLI or using our managed hosting service and syncing the configuration to your code repository. In the following quick start guide we will walk you through both approaches.

Using the CLI

To get started using the CLI you first need to install mocki from npm. To do this run the following command:

npm install -g mocki

The next step is to create a configuration file for your service. The configuration is specified in YAML and follows the structure defined in the Configuration section. Here is a simple configuration file to get started:

name: mocki
port: 3000
endpoints:

- path: /hello
  method: get
  responses: - statusCode: 200
  body:
  message: Hello from Mocki!
  

Save this file as config.yml and run the following command in the same directory as your config file to run your mock service locally:

mocki start --config config.yml

You should now be able to make a request to http://localhost:3000/hello which will respond with the following body:

{
"message": "Hello from Mocki!"
}

Using managed hosting

To get started using our managed hosting simply sign in with GitHub to set up your API from a configuration file in your GitHub repository or using the visual editor.

Configuration

Your mock service is defined in a single YAML-file. It the following guide we will walk you through the different ways you can configure your mock service.

Conditional responses

If you want to simulate a response based on a condition it is possible to use a conditional response.

Conditional responses are defined as below:

endpoints:

- path: /conditional
  method: get
  behavior: conditional
  responses: - statusCode: 200
  condition:
  operator: eq
  comparand: headers.authorization
  value: valid
  body:
  message: valid header - statusCode: 401
  condition:
  operator: eq
  comparand: headers.authorization
  value: invalid
  body:
  message: invalid header
  

To trigger the conditional response behavior we need to include the behavior: conditional property on the endpoint.

The logic that determines the condition is defined in the condition property on the each response.

operator defines which operator to use when comparing the comparand property to the value property. Currently, only eq is supported.

comparand is the dynamic value that should be used in the comparison. In this case we use headers.authorization to access the authorization header in the request. params includes all path parameters and query includes as query parameters in the request.

value is the static value to compare the operand to.

Random responses

Sometimes you want to randomize the response returned from your mock service. A typical use case is to simulate random errors occuring.

To do this define an endpoint with a random behavior:

endpoints:

- path: /random
  method: get
  behavior: random
  responses: - statusCode: 200
  body:
  color: red - statusCode: 200
  body:
  color: black
  

This will randomize the response body between { "color": "red" } and { "color": "black" }

Fake data

To generate realistic mock data there is a possibility to use the !Fake tag in your configuration file.

For example:

endpoints:

- path: /fake
  method: get
  responses: - statusCode: 200
  body:
  firstName: !Fake firstName
  lastName: !Fake lastName
  email: !Fake email
  address: !Fake streetAddress
  phone: !Fake phoneNumber
  createdAt: !Fake pastDate
  company: !Fake company
  

Delays

To simulate a delay in your services response use the following syntax:

endpoints:

- path: /delay
  method: get
  responses: - statusCode: 200
  delay: 500
  body:
  message: delayed by 500 ms
  

delay is the number of ms to delay the response

Branch filter

If you configure your project from a GitHub repository, you can limit the branches that will get an API stage by using a branch filter.

branchFilter: master|develop # Regular expression
endpoints:

- path: /hello
  method: get
  responses: - statusCode: 200
  body:
  message: This stage was created from either master or develop!