Postman really supercharges your API

#postman #api #devrel #onboarding

It’s been a while since I used Postman for the last time. Now that we had a need to test one endpoint quickly I decided to tap into it again. What was my surprise when I discovered that Postman can do much more than what we used to see a couple of years ago. It’s amazing how a small, toylike Chrome plugin has evolved to a production-ready test framework with a nice business model behind. Here is why we decided to go for Postman to supercharge our coupons management API platform.

UX or actually DX

Postman is super easy to use. No tutorial is required. You just open the builder and start writing requests. No matter if you’re dev, QA, ops guy or a PM you know the way it works right away. This is why it has become a useful tool for communication at Voucherify. E.g. we can use it to give a demo to customers. Or, we can communicate issues related to a particular endpoint. Finally, thanks to the request History we can experiment with various corner cases ensuring the API is errorless and gives good overall developer experience. On top of that, Postman has a great utility features to get you started. Several things like headers autocomplete, cURL import, code generators, bulk edit, request duplicates make the onboarding process smooth.

Collaboration

The usability features described above would be half-productive if it wasn’t for sharing capabilities. With Postman collections sharing is just a few clicks away (have I mentioned collections?). The role manager you can find in Team Library gives you the ability to define who can see what in your organisation. Although it’s a paid feature, in our opinion it’s worth it. Especially when it starts with $5 per month.

Test framework

Postman has evolved as an advanced testing tool too. By introducing parameters and assertions you can create pretty complex test scenarios. Likewise, putting JavaScript interpreter into Tests section gives you extra capabilities. Watch this:

In this example we check if the response which consists of the list is correct. Notice that not only can you write pure JavaScript, but the postman guys also included lodash and other utilities, the full list of supported libraries is available here. But there’s more, if you look closely on the endpoint’s URL you can see that we used a parameter there. You should know that apart from built-in dynamic variables like these:

*

{{$guid}}

: Adds a v4 style guid

*

{{$timestamp}}

: Adds the current timestamp.

*

{{$randomInt}}

: Adds a random integer between 0 and 1000

Postman gives you capability to define your own variables which, in turn, can be grouped into environments. This is a powerful feature because we can quickly switch tests’ target between production and local machines. Furthermore, environments can be easily shared among team members or customers so this makes testing and troubleshooting even faster. In future, I expect it to be helpful in covering different versions of API. As for now we’ve managed not to introduce breaking changes in v1. Another nice feature, which makes Postman a serious test framework is the capability of storing context between tests. Take one of the basic Voucherify’s flows for example:

create a unique one-off voucher (returns a unique code that can be redeemed only once)
validate the code (informs client applications if the code is valid and returns discount value if true)
redeem voucher (actually marks the voucher as used so that it becomes invalid)
redeem voucher again (should fail because of the limit)
get redemption history for the voucher (should return redemptions’ details)

After the first request is invoked Voucherify returns a unique code. The key thing here is that the other requests depend on this code, so we need to find a way to pass it. Postman’s Environment and Global storages come to the rescue here. See the example below:

We put a one-liner (postman.setEnvironmentVariable method) and from now on we can refer to the TC1-code parameter in other requests. Be it in a request URL, payload or test section.
Tip: After the test case is finished, it’s good to clear the context so that it doesn’t interfere with other scenarios.

Customer onboarding

Finally Postman is a good tool to onboard developers to your API. Developer experience is super important in our business. That’s why tools like Run in Postman or Postman Documenter are tremendously helpful to make the first steps easy and let developers run more advanced scenarios. This is how they can quickly ensure that Voucherify meets their coupon software requirements. Run in Postman is a part of sharing feature. It makes the collection public so that anybody who has a free Postman account can import it. And the Run in Postman generator is the icing on the cake. This is how it looks like in our case:

Postman Document — another one-click tool giving so much value in onboarding stage. The tool generates and publishes an interactive documentation for your requests collection. To make things better, this online spec enables you to generate code snippets for requests in one of 7 flavours (cURL, jQuery, Node, Ruby, PHP, Go, and Python).

Continuous integration

We have yet to check out Newman — a command-line collection runner. Not only is it a nice feature for terminal junkies but it also opens a way to integrate Postman tests into a continuous integration pipeline. There’s already a tutorial how to connect it to Jenkins. Newman combined with workflows sounds like good candidate for a powerful tool for running comprehensive test suites.

Pricing

$5 per month for all these features? That’s what we call super benefit to cost ratio. Especially when you compare it to Runscope which gives you a bit more features, but start from $79, though. We liked Postman from day one. It’s become a common tool at Voucherify because it supports our API-first platform in many areas such as quality assurance, customer support or finally developer onboarding. And really, they do this seamlessly. I like to think that Voucherify will achieve the same level of developer experience when it comes to coupons management software.

Originally published at www.voucherify.io.