I’ve been writing a bit about OpenAPI lately and I realised that I didn’t share how I’m creating local, test versions of production APIs to work with while I develop new client code or test SDK features. The recipe is simple: you will need an API spec, the excellent open source tool Prism and an HTTP client. Mix it up and be ready to change your API development workflows forever.

Start with an OpenAPI Spec

If you’re already working with OpenAPI, try your own. Otherwise, check if your favourite API provider has one. I’m working at Nexmo and we have quite a selection so pick one of these and look for the “Download” button on the API reference.

Use Prism to Pretend to be Your API

Prism runs as a local server, and it “pretends” to be your API. When it starts up, it announces which URLs it knows about, and when you make requests to those URLs, it will attempt to respond appropriately, using the default or example values from the OpenAPI spec. If you provided complete responses, it will use those.

Prism is a NodeJS tool, so install it like this:

npm install -g @stoplight/prism-cli

Then if your OpenAPI spec is openapi.yml, start the server with a command like:

prism mock openapi.yml

Give it a few seconds and it’ll announce itself (usually on https://localhost:4010).

Use the Mock Server

Now you can use any HTTP client to make requests to your new API platform and see how it performs! For a quick way to get started, try importing your OpenAPI spec into Postman to get a collection of requests that are ready to go!

Remember that Prism only has the information in the OpenAPI spec file, it can’t check your real credentials or do any logic on the server side.

Take Prism to the Next Level

By specifying multiple responses, you can teach Prism all the various responses that might come back from your “real” API. This is great for testing success cases, but it becomes really really powerful when it comes to testing failure cases. I’d really prefer customers use this rather than flatten our servers with traffic trying to generate the rate limit failure message, for example :)

In OpenAPI, you can specify as many responses as you like, and give them names. Here’s a snippet from a Nexmo OpenAPI spec:

          content:
            application/json:
              examples:
                throttled:
                  summary: Request limit exceeded
                  value:
                    status: "1"
                    error_text: Throttled

                missing-param:
                  summary: Missing a parameter
                  value:
                    status: "2"
                    error_text: Missing api_key

Here you can see a couple of examples of error responses. I’ve added the examples in full to the spec and named them. Using the names like throttled, I can then get Prism to return exactly this response (by default it returns the first applicable one it finds) by using the __example query parameter when sending the request.

So if I usually send a request like GET /verify/search?request_id=123456 then I can instead send GET /verify/search?request_id=123456&__example=throttled to get a specific response. I use this extensively to make sure that the code I write (and sometimes that’s library code so it can easily end up in other people’s projects!) responds predictably and in a sane manner to all the possible responses that might come back from the API.

Having tools like this is moving OpenAPI beyond being “just” a documentation tool, and already I can’t imagine working with APIs without it.