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-cli from npm. To do this run the following command:

npm install -g mocki-cli

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:

{
  "hello": "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.

Basic information

The first part of your confirmation consists of two properties: name and port.


name: mock-service
port: 3000

name is only used when you deploy your service to our managed hosting. This will be included in your service url and has to be unique. In this case the service url will be https://mock-service.api.mocki.io.

port defines the port used when running the service locally through the CLI.

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
        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
endpoints:
  - path: /hello
    method: get
    responses:
      - statusCode: 200
        body:
          message: This stage was created from either master or develop!