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.