OpenAPI is the Static Truth and Postman Collections are Real World Derivatives of that Truth
20 Dec 2019
I was talking with the Optic folks this morning about API definitions when they asked me for my opinions on what the difference between OpenAPI and Postman were. A question that isn’t easy to answer, and will produce many different answers depending on who you are talking with. It is a question I’ve been struggling with since before I started at Postman, and will continue to struggle with over the coming years as their Chief Evangelist. The best I can do right now is keep writing about it, and continue talking with smart people like Optic, and iterate upon the answer until I can better see what is happening.
Here is how I see things currently: OpenAPI is the static truth, and Postman collections are the real world, real time derivative’s of this truth. Each individual Postman collection reflects the derived value of an API, representing how a developer, application, or system integration is applying this value in the real world. Now if you squint your eyes, all of those Postman collection derivatives roll up into a single OpenAPI truth. OpenAPI is essential for nailing down what the overarching truth of what an API contract delivers, while Postman is essential in quantifying, realizing, and executing this truth on the ground for a specific business use case. There are definitely ways in which OpenAPI and Postman collections overlap, but then there are the ways in which they bring different value to the table.
When it comes to capital G Governance OpenAPI is more meaningful to business leadership—it represents a more constant truth that can then be translated within services, tooling, and defining policy at the macro level. When it comes to lowercase g governance Postman collection is more meaningful to developers, because it represents the transactions they need to accomplish each day, which are derived from the greater truth, but have more context regarding each specific business transaction that a developer is expected to deliver. This is why OpenAPI and an API first approach within the enterprise can still be seen as academic, and is something handed down from upon high from architects and management, where Postman collections represent the truth on the streets within an enterprise--illuminating the rift we can see within the enterprise when it comes to API definition adoption.
This answer is something I will keep working on. I’m not happy with my overall understanding of the differences between how OpenAPI and Postman collections are used within the enterprise. Coming from a very academic OpenAPI reality as the API Evangelist into a very street Postman collection reality as Chief Evangelist has left me unbalanced. I’m interested in deepening my understanding of not just what is possible with each API definition format, but how they are actually being used to grease the wheels of API operations within the enterprise. I’m guessing that the differences between these realties will very much color what the real differences between OpenAPI and Postman are, how they get used on a daily basis within companies, organizations, institutions, and government agencies. I see both API definition formats as critical to the overall API life cycle, but exactly how I am still a little fuzzy. I’ll keep working on my answer to this question, and see where I land in the future, when it comes to making them both work in a syncrhonized way.