Prism

Working with APIs is great but sometimes you don't need to work with the real API to get development work done. One tool that you may find useful to include in your development workflow is Prism from Stoplight. Prism is a mock server that imitates our live APIs. You can run it locally to test your API calls during development, without incurring any usage costs.

Prism understands the OpenAPI specs we publish for each of our APIs, so you can use this approach to work with any of the Vonage APIs.

Install Prism

Prism is a node.js tool, so you will need to have node.js installed locally. Full documentation and installation instructions are available but the quick version is an npm install command:

npm install -g @stoplight/prism-cli

Check the command is installed and working by running prism --version from a terminal.

Get the OpenAPI Spec

The easiest way to find the OpenAPI specification for any of our APIs is to choose it from the list of API references and then select "Download OpenAPI 3 Specification" from the API reference for the API you're interested in.

We do also publish all our APIs on GitHub, look under definitions/: https://github.com/nexmo/api-specification

Once you have the .yml file you want, you are ready to start Prism.

Start a Mock Server with Prism

From the terminal, start prism with a command like this:

prism mock [api-spec.yml]

For example for Number Insights API, my command and its output look like this:

$ prism mock number-insight.yml
[12:13:06] › [CLI] …  awaiting  Starting Prism…
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/basic/json?number=1%295-2%209%2B2&country=UV
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/standard/xml?number=67-64%298427&country=OU&cnam=false
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/advanced/async/json?callback=sunt%20deserunt%20dolore%20id&number=%2B1208&country=CM&cnam=false&ip=accusamus
[12:13:06] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/advanced/xml?number=-47&country=MU&cnam=false&ip=non
[12:13:06] › [CLI] ▶  start     Prism is listening on http://127.0.0.1:4010

The final line of the output shows you where Prism is running; for me that's locally on port 4010.

Make API Requests to Prism

With the URL shown in Prism's startup output as the base URL, use your favorite HTTP client to try the example API. The example above used the Number Insights API, so you could make a curl request like this:

curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777"

The response from Prism has the same fields as the live API and some example values, making it an ideal replacement for the "real thing" when testing.

For an even easier way to work with Prism and make API requests, try importing the same OpenAPI spec you gave to Prism into Postman and use the ready-made collection of requests. By changing the {{baseUrl}} variable, you can quickly use Postman and Prism to explore the shape of any Vonage API without charges.

Use Prism with Your Application

Our SDKs all offer support for changing the Base URL that API requests are directed to (detailed in the README of each of the libraries) to enable you to use other endpoints for testing.

Prism Advanced Usage

Once you've settled in with Prism, here are some tips for taking things to the next level.

Request a Specific Response

Our APIs can return error responses in some situations, and it can be difficult to recreate those error situations on the live platform. Using Prism gives an opportunity to test applications against all the possible responses.

Some of our API specs have error responses described in detail, and you can use the name of the response to ask Prism to return it.

For example, in the Verify API, you will find this in the example responses in the API spec:

              examples:
                success:
                  summary: Request was started
                  value:
                    request_id: abcdef0123456789abcdef0123456789
                    status: "0"

                throttled:
                  summary: Request limit exceeded
                  value:
                    status: "1"
                    error_text: Throttled

                account-disabled:
                  summary: Account is barred
                  value:
                    status: "8"
                    error_text: The api_key you supplied is for an account that has been barred from submitting messages.

                rejected:
                  summary: Rejected
                  value:
                    status: "15"
                    error_text: The destination number is not in a supported network

By default, Prism returns the first response which is great, that's a good example of what the API will usually return.

However to check your code handles some of these other possible responses would not be ideal. This is where Prism can help a lot! By appending a __example parameter to your request, you can select which of the examples Prism should return. For example to take a curl request to Verify API but get it to return the "throttled" response, it would look like this:

curl "http://localhost:4010/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777&brand=Test&__example=throttled"

By using Prism in this way you can check your application's behavior with all the responses the API can return.

Better JSON Handling with JQ

If you're working with JSON on the command line as in the curl examples shown here, try the tool jq to level up how you work with JSON. It's a great formatter in its own right, and can extract particular fields from the response or handle the data in other ways too.

In its simplest form, use it to get a nicer output from the curl example we used when first testing out Prism:

curl "http://localhost:4010/basic/json?api_key=abcd1234&api_secret=VerySecret1&number=44777000777" | jq "."

Improve this page