Introducing Governance for Publishing Collection Documentation

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?

Governance on publish documentation
Governance for publishing documentation workflow

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.
Creating request for publish documentation
Creating a request for publishing collection documentation
  • API producers/developers will get a notification (email and in-app) once the community manager approves or denies the publish request.
Notifications for updates on publish requests
Notification for updates on publish requests
  • 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.
Email notification when a publish request is sent by a developer.
Email notification when a publish request is sent by a developer
  • Community managers can view all the publish requests in the Manage Public Elements option on the Postman app.
Manage public elements dashboard for documentation requests
  • 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.

 

The community manager will see this screen when responding to any pending requests.
The community manager will see this screen when responding to any pending requests
If the community manager decides to deny the request, they can provide relevant information using a note.
If the community manager decides to deny the request, they can provide relevant information using a note
  • Community managers can preview the published documentation by clicking on Edit Settings.
Edit settings screen
Edit settings screen
  • 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.
Community managers can access published documentations and unpublish any published documentation using “manage public elements.”
Community managers can access published documentation and unpublish any published documentation using Manage public elements

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


What do you think about this feature? Tell us in a comment below. You can also give product feedback through our Community forum and GitHub repository.

Comment

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.