Share article:
How we use Postman internally as an API-First company
At MessageMedia we pride ourselves on being API First. However, there’s a number of challenges in making our products publicly available to our customers and the developer community. Since API First companies have become more prevalent, there are a number of new tools for driving adoption and ensuring your APIs are easy to use. We have recently started using Postman to improve our APIs both internally and externally.
Educating your team with Postman
Postman is an amazing tool for internal education, for both your tech teams and non-technical teams. It allows your tech team to easily illustrate the concept of an API, and allows non-technical staff to make API calls without needing to learn a programming language.
At MessageMedia we have a number of non-technical staff and it’s essential they understand our products and how they work from a technical standpoint. In particular, the sales team’s success depends on their ability to understand and explain our API features to customers with authority and clarity. Since conducting company-wide training and walking our entire team through the basics of making API calls, we’ve received many requests for more Postman collections.
Incorporating Postman into the Developer Relations toolset
In the Developer Relations team, we’re responsible for creating documentation that allows developers to easily use our APIs. Our goal is for customers to spend less time figuring out how to use the APIs, and more time using business messaging in novel ways that drive value for their business.
We’ve created Postman collections for most of our core APIs and published them on our documentation and our GitHub, with instructions for each. These have been used internally by members of the organisation, and have been popular with support and sales staff who use them for customer education and assistance.
These collections have been particularly useful at events we sponsor, as we typically run a competition to see how many people can send a message through our Messaging API. Since incorporating Postman collections into our toolset we’ve seen a marked increase in the number of people sending their first messages with Postman, as it’s easier than ever. The first conference after we published the Postman collections on our Github, we had an approximately 89% increase in the number of people who were able to send a messaging, simply because it was so easy to do!
Tips for sharing collections
When sharing postman collections that have authentication requirements there are a few considerations. You want to avoid the risk of accidentally sharing your authentication credentials when you make a change to a shared collection, but also make it as obvious as possible where the authentication credentials are needed. The easiest way to do this is with shared variables.
You can find the variables by entering the edit screen on the final tab within your collection. In the context of the MessageMedia APIs, for most situations, you will be using basic auth, which requires two variables – a username and a password. For our APIs, the username is your developer key and the password is your developer secret. You’ll need to create two new variables for your username and password:
Reference these variables in the authorisation Tab, using bracket notation:
The great thing about this setup is when you share a collection, the recipient will get the full set up without your actual username and password values. They will be able to enter their own developer credentials in those slots, and the collection will work. We’ve set this up on the top level of the collection and then all other API calls that are a part of this collection have the authorisation type set to “inherit from parent”.
Sharing your collections has also been made super easy by Postman. “Share collection” is the first option in the edit menu for the collection. Postman offers two means by which to share it: an embedded button and a link. The button is by far the easiest way to share, as the button will automatically open up the collection in the postman app or prompt the user to download it. We created static buttons that we could embed in the markdown for our Apiary documentation:
Conclusion
These are just some of the features of Postman that we have found really useful at MessageMedia. There are even more capabilities, like mock servers and team workspaces. We will be continuing to use Postman collections as a part of our Developer Relations toolset and working with the tech team to create collections for APIs as they get released. You can get started with our Messages API quickly and easily today.
(function (p,o,s,t,m,a,n) {
!p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
!o.getElementById(s+t) && o.getElementsByTagName(“head”)[0].appendChild((
(n = o.createElement(“script”)),
(n.id = s+t), (n.async = 1), (n.src = m), n
));
}(window, document, “_pm”, “PostmanRunObject”, “https://run.pstmn.io/button.js”));
