Mocking REST APIs with Imposter

4 min readNov 22, 2019

We all know that integration testing is important. But when a third party service goes down and causes all your integration tests to fail you realise how brittle this can make your CI/CD pipeline. Sometimes you need to isolate yourself and create a mock of an API.

Need a quick mock of a REST API? Say hello to Imposter.

Using OpenAPI/Swagger? Check out the other article: Mocking APIs with OpenAPI and Imposter.

A simple API

Let’s start with a simple API. In keeping with the rules of the internet, this must involve cats. To keep things simple we’ll define a single endpoint for now, named /cats that will return a JSON array like so:

[
  {
    "id": 1,
    "name": "Fluffy",
    "type": "Persian"
  },
  {
    "id": 2,
    "name": "Leo",
    "type": "Bengal"
  }
]

To represent this API, we are going to use Imposter. Imposter is an open source tool for easily creating mocks. In this scenario we will use the built-in REST plugin.

Note: if you already have a Swagger/OpenAPI specification, you want to use the OpenAPI plugin instead.

The configuration

Here is the configuration file for our endpoint:

---
plugin: rest
contentType: application/json
resources:
  - path: "/cats"
    response:
      staticFile: cats.json  - path: "/cats/:id"
    type: array
    response:
      staticFile: cats.json

Important: Your configuration file must be named with the suffix -config.yaml — for example: cat-config.yaml

A few things to call out:

We’ve defined the endpoint /cats to return the contents of our sample JSON file; in other words an array of cats.
We’ve also said that, because the response file is a JSON array, we want to allow querying of individual items by their ID, under the /cats/:id endpoint.
This example assumes you’ve named the file containing your JSON array cats.json and that it is in the same directory as the configuration file.

Start the mock

Now we’re going to start a mock server that you can call from your client code/web browser/CLI.

Preflight checks

Ensure you have Docker installed and running.
You should run the command in the next section from the directory containing your JSON sample response file and Imposter configuration file:

$ ls -l
-rw-r--r--  1 pete  staff  104 16 Sep 13:55 cat-config.yaml
-rw-r--r--  1 pete  staff  998 16 Sep 13:55 cats.json

Let’s go!

Start the mock server as follows:

$ docker run -ti -p 8080:8080 \
    -v $PWD:/opt/imposter/config \
    outofcoffee/imposter

You should see log output including the lines:

Loading configuration file: /opt/imposter/config/cat-config.yaml
Loaded 1 plugin configuration files from: [/opt/imposter/config]
...
Adding GET object handler: /cats
Adding GET array handler: /cats/:id
Mock engine up and running on http://localhost:8080

Congratulations! 🎉 You now have a working mock server. Let’s test it.

Testing your mock

Let’s try a test from the command line:

$ curl "http://localhost:8080/cats"
[
  {
    "id": 1,
    "name": "Fluffy",
    "type": "Persian"
  },
  {
    "id": 2,
    "name": "Leo",
    "type": "Bengal"
  }
]

It works! Your mock is returning the example response at the path /cats along with the HTTP 200 status.

Returning single items

Because the response file is a JSON array, we can query individual items by their ID, under the /cats/:id endpoint. Let’s try:

$ curl "http://localhost:8080/cats/1"
{
  "id": 1,
  "name": "Fluffy",
  "type": "Persian"
}

Great! A single item from the array 😺

Because we specified the placeholder :id in the configuration for our array endpoint, Imposter finds the item in the array with the corresponding JSON key (‘id’) and value (‘1’).

More than simple APIs

Imposter gives you the full range of HTTP methods, as well as the ability to specify custom headers and status codes. Here’s a more advanced example:

---
plugin: rest
path: /example-two
contentType: "text/html"
method: POST
response:
  statusCode: 201
  headers:
    X-Example: "foo"
  staticData: |
    <html>
      <head>
        <title>Example</title>
      </head>
      <body>
        Hello, world!
      </body>
    </html>

Highlights:

This endpoint will only be accessible via the POST HTTP method
We’ve indicated that status code 201 should be returned
We’ve set the content type of the response to HTML
A custom header will also be returned

Test this with curl:

$ curl -X POST "http://localhost:8080/example-two"
<html>
  <head>
    <title>Example</title>
  </head>
  <body>
    Hello, world!
  </body>
</html>

Summary

You now have a simple mock server. Its endpoints are built from the configuration file you provided. This means that if you add further endpoints, or make changes, Imposter will mock those too.

If you update your configuration file, just stop/start Imposter to see the changes.

Tip: To stop the running mock, just type CTRL+C in its terminal.

Customising your responses with scripts

Imposter is simple to learn, but is also very customisable. If you outgrow returning static example responses from your specification, you can use scripts, written in JavaScript or Groovy, to control the response your mock returns.

For more information on scripted responses, check out the documentation.

Looking for a hosted solution?

Do you want to try Imposter, but don’t want to run it yourself? Check out the hosted Imposter service at www.mocks.cloud

It’s free to try!

Example code

Get the example code on GitHub.