I have been working on a project where our team is trying to streamline API development workflows. We are using Postman heavily for testing & collaboration but I feel such as we are not taking full advantage of everything it offers. We stick to creating collections, running tests & syncing with our repo. I have seen teams use Postman in much more advanced ways, such as integrating with CI/CD pipelines or setting up detailed monitoring.
I wanted to ask: what are some best practices or advanced tips you have followed to make API development smoother in a collaborative environment? How do you organize collections for multiple environments & do you recommend any specific naming conventions or structures?
While exploring different tools for project management I came across a JIRA Course that explained workflows in detail. It got me thinking if Postman has something similar that we might be underusing.
PS: My response is a bit random, and the recommendations are not tailored towards anything specifically, but they may still be helpful.
How you structure a Workspace always depends on the team and the specific use case for that Workspace. I can quickly go down a rabbit hole with recommendations on Workspaces and Collections, especially if we start to talk about more granular things. But on a high level and more generally, I often recommend:
Start from the team structure and implement RBAC. Who can access what? Always operate on POLP(Principle of Least Privilege), which reduces who can publish public artifacts and is great for reducing exposure of sensitive data. People on your team should only get permissions they NEED. For most people, having the developer role in a team is sufficient.
More Workspaces. Fewer Collections in Workspaces. It is very easy and convenient for workspaces to become extremely ambiguous and overwhelmed with collections
Always have one base collection that everyone else contributes to(again, POLP). Every addition to that collection should come through a pull request, similar to how developers have a master/main branch in a GitHub repository, either for Internal, Partner or Public Workspaces. This structure promotes collaboration within teams and ensures that changes go through one reviewer. Some teams may choose to prioritize speed over version control.
Use the Private API Network and encourage teams to actively publish there. It is great for internal API discoverability.
There is no rule of thumb for managing environments; it depends on the workspace use case. One paradigm is to model after server environments(e.g, dev, stage, prod), other teams may model differently, but ultimately abstract common use cases/domains with common variables and create an environment across domains. I’ve seen teams do (web, desktop, mobile).
For Public Workspaces
My recommendation for public workspaces is always to do everything recommended for internal and then optimize for public discoverability. A few things that people do not pay enough attention to for public workspaces that I have noticed are:
Terrible documentations(obviously)
You can optimize for SEO. Most publishers don’t know this. Some recommendations are:
Add descriptions to Collections, Workspaces, and APIs. It’s a small change, but it goes a long way.
Update your personal & team public profiles and your PAN page. Going through a Team verification process on the Network provides you with a checklist of things to do and guides you through the entire process.
Including an image in your Workspace level documentation can improve its public visibility.
At the collection level, listing out the folder structure and hyperlinking each folder/request as a form of reference/table of contents helps with indexing.
Documentation should not only be at the Collection level, but also granular at the request level.
In addition to having good documentation, set up Guided Auths. It helps consumers get started easily, reduces TTFC(Time To First Call), and aids onboarding. This also applies to teams working in internal workspaces.
.