Introducing Governance for Publishing Collection Documentation

Akshay Deo

August 7, 2022

In 2016, we released a feature that helps Postman users to document APIs directly from collections. Since then, millions of users have used this feature to improve their API documentation workflow. The best part of our API documentation is that it evolves with the collection without extra work.

As bigger teams (especially enterprises) started adopting Postman, governance became a critical feature to ensure the security and privacy of data. We realized that a sophisticated access-control system would solve this problem efficiently. So, last year, we released more structured and easier access-control management. With this new access-control system, we have a role, Community Manager, to manage public visibility of workspaces and team profiles. Today, we are excited to announce that publishing documentation will go through the same approval process as workspaces and collections. This feature is available for teams on the Postman Enterprise plan.

How does it work?

For API producers/developers

• Nothing changes except users won’t be able to publish the collection documentation independently; they will have to raise a request to publish to community managers of the team.
• API producers can add a note regarding the need to publish the documentation.

• API producers/developers will get a notification (email and in-app) once the community manager approves or denies the publish request.

• API producers/developers can retract the request if they want to by navigating to publish it.

For community managers

• Community managers will get an email and an in-app notification when a new publish request is created.

• Community managers can view all the publish requests in the Manage Public Elements option on the Postman app.

• Inside Manage public elements, community managers can see all the pending requests and already published documentation under the documentation tab.
• If community managers have access to the underlying collection associated with the publish request, they can modify the settings before approving the publish documentation request.

• Community managers can preview the published documentation by clicking on Edit Settings.

• Once everything is updated, community managers can decide to approve or deny the request. On approval, the documentation will be instantly available on a public endpoint.
• Community managers can unpublish any published document using the Manage Public Elements menu.

We are excited to launch this feature and further enable airtight governance on the Postman API Platform. Let us know if you have any feedback.

Try Postman now