Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Breaking Postman API Collections Into Meaningful Units Of Compute

DZone's Guide to

Breaking Postman API Collections Into Meaningful Units Of Compute

In this post, we take a look at what one organization has done to better work with Postman and organize their APIs for their users.

· Integration Zone ·
Free Resource

The State of API Integration 2018: Get Cloud Elements’ report for the most comprehensive breakdown of the API integration industry’s past, present, and future.

I’m fascinated with the unit of compute as defined by a microservice, OpenAPI definition, Postman Collection, or any other way of quantifying an API-driven resource. Asking the question, “how big or how small is an API?”, and working to define the small unit of compute needed at runtime. I do not feel there is a perfect answer to any of these questions, but it doesn’t mean we shouldn’t be asking the questions, and packaging up our API definitions in a more meaningful way.

As I was profiling APIs, and creating Postman Collections, the Okta team tweeted their own approach to delivering their APIs at me. They tactically place Run in Postman buttons throughout their API documentation, as well as provide a complete listing of all the Postman Collections they have. Showcasing that they have broken up their Postman Collections along what I’d consider to be service lines. Providing small, meaningful collections for each of their user authentication and authorization APIs:

Note: Just an example, 'Run in Postman' button does not work.

Collections Click to Run
Authentication Run in Postman
API Access Management (OAuth 2.0) Run in Postman
OpenID Connect Run in Postman
Client Registration Run in Postman
Sessions Run in Postman
Apps Run in Postman
Events Run in Postman
Factors Run in Postman
Groups Run in Postman
Identity Providers (IdP) Run in Postman
Logs Run in Postman
Admin Roles Run in Postman
Schemas Run in Postman
Users Run in Postman
Custom SMS Templates Run in Postman

Okta’s approach delivers a pretty coherent, microservices approach to crafting their Postman Collections, providing separate API runtimes for each service they bring to the table. Which I think gets at what I’m looking to understand when it comes to defining and presenting our APIs. It can be a lot more work to create your Postman Collections like this, rather than just creating one single collection, with all API paths, but I think from an API consumer standpoint, I’d rather have them broken down like this. I may not care about all APIs, and if I’m just looking at getting my hands on a couple of services–why make me wade through everything?

I have imported the Postman Collections for the Okta API and added them to my API Stack research. I’m going to convert them into OpenAPI definitions so I can use them beyond just Postman. I will end up merging them all back into a single OpenAPI definition, and Postman Collection for all the API paths. However, I will also be exploding them into individual OpenAPIs and Postman Collections for each individual API path, going well beyond what Okta has done. Further distilling down each unit of compute, allowing it to be profiled, executed, streamed, or other meaningful action in isolation, without the constraints of the other services surrounding it.

Your API is not enough. Learn why (and how) leading SaaS providers are turning their products into platforms with API integration in the ebook, Build Platforms, Not Products from Cloud Elements.

Topics:
integration ,postman ,apis ,openapi

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}