Mocking APIs with OpenAPI and Imposter

In our fast moving and API driven world, teams often need to build an API’s client (mobile, web, service) alongside its implementation.

Smart client developers might agree an API specification with the backend implementation developers. This enables both groups to work simultaneously, and hopefully in a relatively loosely coupled fashion.

But when testing your client code, a specification document only gets you so far.

Wouldn’t it be better if your specification was also a live mock of the backend service? Say hello to Imposter.

A simple specification

Let’s start with a simple API. In keeping with the ancient traditions of our people, we will model a pet store. To keep things simple we’ll define a single endpoint for now, named /pets that will return a JSON array like so:

[
  {
    "id": 101,
    "name": "Cat"
  },
  {
    "id": 102,
    "name": "Dog"
  }
]

To represent this API, we are going to use OpenAPI (formerly known as Swagger). This example uses version 2.0 of the specification, but you can use more recent versions too.

The specification

Here is the Swagger specification for our endpoint:

---
swagger: "2.0"
info:
  version: "1.0.0"
  title: "Swagger Petstore"
consumes:
- "application/json"
produces:
- "application/json"
paths:
  /pets:
    get:
      description: "Returns all pets from the system"
      produces:
        - "application/json"
      responses:
        "200":
          description: "A list of pets."
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
          examples:
            application/json: |-
              [
                {
                  "id": 101,
                  "name": "Cat"
                },
                {
                  "id": 102,
                  "name": "Dog"
                }
              ]
definitions:
  Pet:
    type: "object"
    required:
      - "id"
      - "name"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"

A few things to call out:

• We’ve defined the endpoint /pets as expecting an HTTP GET request
• We’ve said it will produce JSON responses
• One response is defined for the HTTP 200 case
• We’ve defined a basic data model in the definitions section
• We’ve provided an example response — the same JSON array described earlier

Tip: There’s much, much more to Swagger than this. Check out the specification for more info.

What’s next?

On its own, the specification is a useful way to document and share your API. Let’s take it to the next level with a mock service based on this specification that you can actually call from your client.

Creating a mock

All we need to start our mock is a small configuration file. This tells Imposter the name of our Swagger/OpenAPI specification.

Here’s the configuration file:

---
plugin: openapi
specFile: petstore.yaml

Note: This assumes you’ve named your specification petstore.yaml and that it is in the same directory as your configuration file.

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

Preflight check

1. Ensure you have Docker installed and running.
2. You should run the command in the next section from the directory containing your Swagger/OpenAPI specification and Imposter configuration file:

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

Start the mock

You can 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/petstore-config.yaml
Loaded 1 plugin configuration files from: [/opt/imposter/config]
...
reading from /opt/imposter/config/petstore.yaml
Adding mock endpoint: GET -> /pets
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 -X GET "http://localhost:8080/pets"
[
  {
    "id": 101,
    "name": "Cat"
  },
  {
    "id": 102,
    "name": "Dog"
  }
]

It works! Your mock is returning the example response from your specification at the path /pets along with the HTTP 200 status.

Exploring the mock

To explore your mock, visit the UI at: http://localhost:8080/_spec/
This will show you a page that looks like this:

Imposter showing the Swagger UI for an API specification

Summary

You now have a simple mock server. Its endpoints are built automatically from your OpenAPI specification. This means that if you add further endpoints, or make changes, Imposter will mock those too.

If you update your specification 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.