How adding the Run In Postman button changed our API

Author: Adam Bird

3rd July 2019

We recently added the Run in Postman button to both our Developer Dashboard and public API docs. All in all it was a pretty simple experience with just a little bit of learning around some new Postman concepts.

What was really interesting was how we ending up making some subtle changes to our API responses when we viewed it through the Postman lens and subsequently improved our developer experience.

Collections and Environments

The Collections tab in the Postman Client is the place to start. The Run In Postman is essentially a download link for a collection of API interactions to copy into the user’s Postman Client.

Start by defining a series of API interactions and save them to a Collection. You do this by choosing the ‘Save to Collection’ option of the Save button.

The other piece of the puzzle are Environments. This is where you can define values for variables to use in your pre-built interactions. In the following example, Postman will look for variables in the current environment to replace the {{from}}, {{to}} and {{tzid}} values.{{from}}&to={{to}}&tzid={{tzid}}

Thus, if you can provide an Environment with sensible defaults alongside your Collection you’ll make for a far better developer experience.

Adding The Button and Generating an Environment

Once you have your collection adding the button can simply be a matter of choosing the ‘Share Collection’ option and copy the embed code provided. If you have an Environment with sensible static values then you can choose to add this to the embed code. This way the user gets both and can start using your Collection straight away.

If you want to ship an API token then you need to look at creating the Environment programmatically. Fortunately Postman provide a JavaScript function for doing just that.

_pm('env.create', 'Cronofy API', {
  client_id: 'xyz123',
  client_secret: 'k8dkafdhkawuhfdkawufkaufgakufga',
  from: '2016-03-13',
  to: '2016-03-21',
  tzid: 'Europe/London'

In this case, from within our Developer Dashboard, the code output a token for the Application to form part of this statement.

We wanted to take it a stage further than just a credentials. Time is rather important to the Cronofy API and developers get a better experience querying their calendars if the from and to values are current.

We dynamically generate the times (1 day ahead and 8 days ahead) to ensure the developer gets sensible data back from our API. For the tzid (timezone) we use jsTimezoneDetect to sniff the browser timezone so the experience is localized.

Improved API responses == Improved DX

Things got more interesting with another environment variable calendar_id{{calendar_id}}/events

This is the end point for creating events in a particular calendar. It needs the calendar_id but that is only available from the result of another call to list calendars.

We decided to just replace it with a really obvious placeholder.

_pm('env.create', 'Cronofy API', {
  client_id: 'xyz123',
  client_secret: 'k8dkafdhkawuhfdkawufkaufgakufga',
  from: '2016-03-13',
  to: '2016--03-21',
  tzid: 'Europe/London',
  calendar_id: '$$_REPLACE_THIS_$$'

But the API response as a 404 Not Found. Nothing really telling the user what is going on.

It was at this point we realised that if we made our API aware of documentation placeholders then it could guide the developer to get the information they need. So if someone submits an API request with one of these placeholder values, a helpful error message tells them what has happened and what they need to do about it.

Screenshot 2016-03-17 16.40.42

This approach also meant we could add the Run In Postman button to our public API documentation pages. These are a static site hosted on Amazon S3 and have no link to our Developer Dashboard. We’ve therefore just dynamically generated the values we can (from, to, tzid) and put a placeholder in for the client_id, etc.

We let the API do the rest.

Screenshot 2016-03-17 16.57.07

Adding the ‘Run In Postman’ button was super quick. A few hours work and, thanks to our CI pipeline, was in production straight away.

What was fascinating was the view implementing it gave us on to our API and how it guided us to create an even better development experience.

Full Create the Run in Postman button docs from Postman.

Avatar of Adam Bird

Adam Bird

Date: 3rd July 2019 | Category: API, How To