Mocking HTTP responses

Please enter the simulation

wiretap can be used as a full simulation of a real API. We call it mock mode.

To enable it, use the -x or the --mock-mode flags when running wiretap with an OpenAPI Specification.

Try before you buy

mock mode simulates a real, working web API by using an OpenAPI contract to simulate the responses to API calls.

The simulation is based on the OpenAPI contract, which means the API will be contractually correct, ideal for testing and development. Developers can use the mock API to test their code, without having to wait for the real API to be built. mock mode also allows developers to test their code against different scenarios, such as error responses, or slow responses.

mock mode helps developers ensure a client is fully compliant with an API, before the API is even built.

Call it a client, call it a UI - whatever you call it, mock mode helps developers ensure a client is fully compliant with an API, before the API is built. The backend does not need to exist, as long as you have a valid OpenAPI specification, you can use mock mode to simulate the API.

But why?

API First / Design First development is a great way to build APIs. It’s a great way to build clients and UIs too. The API contract is designed first, taking in to consideration all the requirements of consumers of an API, by having the consumers involved in the design.

It allows us to answer questions upfront like:

• Does the API contain all the data and information a client will need?
• Are the data models designed so the client can use them easily?
• Does the UI need to make 500 calls to extract a single page of data?
• Has security, pagination, rate limiting, etc. been considered?
• What happens when the API returns an error?

Answer all of these questions up front with a working API to play around with designs and ideas, without having to write a single line of backend code.

Avoid making costly mistakes to a production API, by trying out new designs and ideas in a mock API first.

Why use wiretap?

Similar functionality is available in other tools, such as Stoplight Prism. However, there are some advantages of using wiretap for mocking over other tools:

• Much faster than Prism, and other tools.
• Has more features, like static hosting, path rewriting the monitor UI and more.
• Distributed as a small single binary, no dependencies, no runtime.
• Lightweight, uses less memory and CPU than Prism, and it’s only 22mb.

How does it work?

When enabling mock mode, wiretap will use the OpenAPI contract to simulate the responses to API calls, before it does this however, it will validate the request against the contract, and if the request is invalid, it will return an error response.

wiretap will also try to locate an appropriate error message in the OpenAPI contract, and return that, otherwise it will return a wiretap specific error message that contains details of what went wrong.

Here is a high-level flow of the logic used to decide what do to with an incoming request, when in mock mode.

Any error that is output in a red box, is an error generated by wiretap itself, and not the OpenAPI contract. When there is no representation of that error in the OpenAPI contract, wiretap will return an RFC7807 compliant error response that has been generated with a relevant HTTP code and a wiretap specific error message.

A good way to find gaps in an API contract, is to have wiretap generate errors for you. It may get messy!

Multiple examples

When a suitable response is found, and there are multiple examples for that response, wiretap will select the first one it finds, which could be any of them, but it’s generally the first one loaded in from the spec.

Preferred examples

If a preferred example is desired for a specific API response, wiretap can be informed to select a specific example by name using the Preferred header.

For example if we have a MediaType with two different examples defined something like this:

  examples:
    NewProductExample:
      summary: "A product to create"
      value:
        name: "pb33f t-shirt"
        description: "A t-shirt with the pb33f logo on it."
        price: 19.99
        category: "shirts"
        image: "https://pb33f.io/images/t-shirt.png"
    SomeOtherExample:
      summary: "Another example"
      value:
        name: "pb33f hat"
        description: "A baseball cap with the pb33f logo on it."
        price: 29.99
        category: "hats"
        image: "https://pb33f.io/images/hat.png"

And we want to extract the SomeOtherExample example, we can use the Preferred header to tell wiretap to use that example.

Override response code

If you want to override the response code that wiretap will return, set a header named wiretap-status-code with the HTTP response code you want to return.

The return code of your mock will then reflect this value and override what ever is defined by the OpenAPI specification.

This will allow you to test how your client handles different response codes with successful mock responses.

Only works when a successful mock response is generated. Available from wiretap version v0.1.11