Ready-to-wear API Collections with OpenAPI and Postman

Have you noticed that API providers are starting to offer “descriptions” of their APIs? These are usually OpenAPI specifications, computer-readable documents that describe every aspect of an API’s endpoints. They can be used to generate documentation, SDKs, but now they can also be used for my favourite API-related activity: poking around! Postman just added a feature to allow importing OpenAPIs and I love it.

The premise is simple: choose Import, and supply an OpenAPI specification. At Nexmo, we hold ours on GitHub so I just click the “Raw” button and paste the URL as a link to import, e.g. https://raw.githubusercontent.com/Nexmo/api-specification/master/definitions/number-insight.yml

You get a collection with all the described endpoints and when you select one, the request is already crafted such that all you need to do is fill in the values you want to send (Pro tip for Nexmo APIs: you’ll usually need to add the api_secret field yourself).

showing the collection and a precanned request

What I love about this is how quickly I can start to poke around in unfamiliar APIs, with very easy access to request formats, descriptions of what should be in each field, and so on. The world of OpenAPI is wide and growing all the time, and as more and more API providers offer API descriptions, more and more developers will have the ability to play in the sand using familiar tools and a new API.

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.