I’m new to Postman, and my initial joy at what it can do is being tempered by realization of a few critical limitations. I suggest it is time for Postman to pivot, and so hope that we users can build pressure for the business case. That is the purpose of this topic. Please join in.
First, some of the requirements I see as critical to API-driven development:
There needs to be a single source of truth which is accessible to API consumers, suppliers, developers, and maintainers. This should be compatible with source control systems, preferably as a single root document which may contain links to additional resources. For example, I want to be able to open discussion of a proposed new endpoint by posting an Issue on Github linking to a feature branch. I want anyone to be able to contribute a PR using whatever software they choose.
That root document should to be versioned, human-readable, extendable, and in an open format. For practical purposes that means starting with JSON Schema.
The document must be able to specify endpoints, data objects, documentation, examples, mocks, tests, variable sets for use in testing, test sets, and probably more that I am not thinking of now.
I suggest that OAS 3.0 covers most of these points, except a glaring deficiency in testing. Postman does well with testing and is making an effort to resolve the other items with the API beta which can import an OAS document. Postman’s glaring deficiency is exporting to OAS, as well as many holes in the import capabilities in the current API beta. Without 2-way conversion, there is no path to a good developer experience.
OAS V3 is now the de facto standard for API specifications, but that a specification without testing is only half a solution. Postman can leverage the work SmartBear has done with OAS specification and validation and the Swagger Editor by extending OAS with custom elements for the missing capabilities (primarily tests and test sets). These extensions should be offered to OAS for inclusion in the next version.
Bi-directional conversion between OAS and Postman could work, but the clean solution would be for Postman to adopt OAS V3 with Postman extensions as their native storage format.
Do you agree?