Updating the SparkPost Postman Collection

One nice thing about SparkPost API documentation is the easy access to a “Postman collection”, which we’ve made available since March 2016. Whether you are just starting out with APIs, or if you are an experienced hand, Postman enables you to get started easily and be immediately productive with your SparkPost based development project.

Spring is in the Air

Jump forward to March 2018, and our collection was in need of spring cleaning, reflecting the numerous API improvements we’ve made (while avoiding breaking changes). We’ve just done that, bringing it into line with current API features and documentation.

Here’s what EUve been Waiting For

With the launch of our public sign-up SparkPost EU service, with API running on https://api.eu.sparkpost.com, we need a flexible solution to support varying URLs.

We also have many SparkPost Enterprise customers with distinct URLs, across three different AWS regions – for example https://customername.api.e.sparkpost.com. Our advice on this in the docs was:

.. seems like we should be a bit more helpful, given the collection contains 100+ requests! Bringing us to:

Postman Collection Variables

Postman has a great feature which we have used to solve this problem – variables can now be of varying scope:

*(from Postman documentation)

This is a really well-thought-out feature from Postman. We can:

  • Replace the hard-wired address in our published collection with {{BASE_URL}} ;
  • Define it inside the collection, preset to the standard sparkpost.com service value, so the collection still “just works” out-of-the-box;
  • .. yet anyone can change it at environment scope if they need to (taking precedence).

When you hover your mouse over the placeholder variable in each call, Postman shows you the current value, along with the scope it’s defined in. Here’s how our collection looks in plain-vanilla form:

If you want to override that value, just create an Environment variable named {{BASE_URL}} and set it to your specific URL, along with your API key. For example, to access our new EU endpoint:

When you hover over the call, you will see the value and scope:

Note the little red square “E” (environment scope) has replaced the orange square “C” (collection scope).

It’s easy to switch between your environments using the Postman drop-down settings on the top right:

Open-sourcing the Collection

The collection itself is hosted via a link to Postman’s own site. That makes it really easy to get started, as your browser knows which app open for you. However, we wanted to go one step further and host the collection source (which is just a big JSON file) on Github, so that you can easily notify us of issues and propose changes or improvements directly.

The Last Post

So, that’s pretty much all there is to it. The collection is now nice and fresh, and you can easily use it with Enterprise and EU endpoints.

If you have any comments, improvements or other suggestions on our Postman collection, please get in touch via Community Slack or direct on Github.