Vonage Makes Its Most Popular APIs Easier with Postman Collections

Guest Author

November 12, 2020· 4 mins

This is a guest post written by Lorna Mitchell, developer advocate at Vonage.

At Vonage, we recently published the Vonage APIs Postman Collection covering our most popular communications APIs. We’ve long encouraged developers to use our OpenAPI descriptions as a starting point since Postman has supported OpenAPI 3.0 imports for a couple of years now. But while importing an OpenAPI description into Postman (or a variety of other tools) is still a pretty excellent way to get started with Vonage APIs, having this new Postman Collection has enabled some magical additions.

In APIs, we often talk of “Time to First API Call,” which is how long it takes a user to successfully make an API call to the product and receive a response. Often you’ll encounter a quick start screen immediately after signup so that you can achieve this goal efficiently. While it’s lovely and reassuring to see the API working, I tend to think there is also value in a measure that’s more like, “Time to First API Call Using Own Tools.” And since many developers already use Postman as their go-to tool, offering this collection can help developers quickly feel “at home” working with our APIs in an API platform they already know well.

Easier API call sequencing in Postman

One of our products available in the new collection is Verify API, which is useful for confirming user telephone details and 2FA (two-factor authentication) applications. It involves a two-step process:

1. The first step gets Vonage to send a pin code to the user’s phone number (using either SMS or text-to-speech, in a choice of languages and with optional retries—so there’s a whole bunch of configuration available) and returns an identifier for the verification process.
2. The second step confirms if the pin is valid by taking the pin code the user received and the identifier from the first step.

From just reading the description, you can imagine it’s a little clunky to add your credentials to two requests, then copy the result of one as a parameter to another. While this is how the API works, it’s not the smoothest developer experience when you’re trying to evaluate a 2FA solution. Having the new Postman Collection now allows us to add a couple of helpful features to make this all easier.

The simplest thing we do is provide an environment with the collection, which contains some variables, including API credentials, which the user can add once in the environment. Plus, the requests already use the values of those variables in the API calls.

In situations like this, where one request feeds data into another, we also use variables—this time at the collection level. Rather than the user setting these, making the API call to request a verification uses a “test” script to store the request_id field from the response into the collection-level variable:

pm.collectionVariables.set("verify_request_id", pm.response.json().request_id);

The API call to check the code already has this variable pre-filled as a value, which means the user only needs to supply the code in order to see the API in action.

Being able to smoothly join up API call sequences like this makes a delightful developer experience—even for someone like me, who knows these APIs so intimately that I could do the whole thing from curl without referring to the documentation, but that doesn’t mean that I want to do it that way! The stored request_id can also be used with another endpoint to search for the detailed status of a request or to send a retry immediately.

By adding a little magic sauce to the API recipe in Postman, we’ve made it easier for developers to get started and quickly add their credentials to all the places they may be needed when working with Vonage APIs. The ability to update variables after a request allows you to join up requests that work in sequence, which all of our developers love (including those of us who work inside the company as well)!

Do you have your own experience or tips to share with the Postman community? We want to hear from you. Learn more about our guest blogger program and submit your idea here.