Workspaces! What are they good for?

Similar to the way humans are social beings, APIs are social and collaborative too. APIs exist among people and when you have people working on APIs, you can end up with people problems. Communication, learning new projects, understanding the scope of work, and staying up to date can become an issue.

At the highest level, Postman’s workspaces were created to solve these people problems. Workspaces help teams maintain a single source of truth for their APIs.

Workspaces: the next step for API source control

Most developers are familiar with using git or similar methods to manage source control for their software code: creating local feature branches, generating diffs with new changes, merging these new changes to a master branch, and so on.

In many ways, API development is different than traditional software development. One difference is the way APIs typically undergo less drastic changes because other consumers rely on them to return predictable responses.

Since APIs are more stable in practice, Postman has a different approach to source control for APIs in particular. When someone updates their instance of a shared Postman collection, Postman generates a diff and automatically merges the new changes to the central collection.

This is how Postman syncs your changes in real time, and enables the team to collaborate with confidence that they’re working off the latest version. #postmanworkspaces

WHAT exactly is a Postman workspace?

Instead of a container, it’s helpful to think of a workspace as a view of all the Postman things you’ve come to use: collections, environments, mocks, monitors, and more. 

It’s important to note that a collection and environment can exist across multiple workspaces, or views. Other elements like mocks and monitors exist solely in the workspace where they are created.

Can you break it down for me?

Let’s look at an example where you share a collection in 2 different workspaces. Workspace A is a personal one where you’re still hammering out details on a collection. You decide to share your collection in Workspace B, a team workspace, and you give the entire team read-only permission for this collection as the default setting.

Changes that you make to the collection in either Workspace A or B will be synced and updates are reflected in this collection that exists in both workspaces. Your teammates can continue to view these updates in Workspace B. 

In the same way, an environment can exist across multiple workspaces too. Say you’re using an environment in Workspace A that contains your personal credentials and access tokens. You want to share this environment, but don’t want to leak your secrets. You should duplicate the environment, remove the sensitive values in the new copy, and then share it in the team Workspace B. If you want this to be a stub for team members to start from, you would leave the permissions as the default read-only. If you want changes to sync for this copy of the environment across both Workspace A and B, give your team or individuals edit permissions.

Now in your personal Workspace A, you create a monitor using the collection and an environment. This monitor exists solely in Workspace A. If your teammates want a similar monitor in Workspace B, they can re-create the same monitor if the same collection and environment is shared in Workspace B.

So then HOW can you use Postman workspaces?

Postman workspaces are a free-form organizational principle. Similar to how we think of collections, workspaces are also not meant to be opinionated or prescriptive ways to structure your APIs and your workflow. The most obvious benefit is staying organized, but how you use workspaces is completely up to you.

Here’s how some teams use Postman workspaces, and how you can too:

By function

Some teams will cluster their activities by a work function, for example technical writers have their own workspace where they focus on documenting the API, QA has a separate workspace for writing tests, customer success as a separate workspace for reproducing issues, and so on.

By product or project

This is also a good way to onboard and introduce new team members to a product or project, for example, at Postman we have all the Postman things related to our mock service in a separate workspace so team members who currently, and in the future, get to work on that product see a tailored view of all the collections and tests associated with mocks.

By partner

If you’re building integrations with external partners or clients, some teams will invite guests to participate in a workspace. You control the view and edit permissions, so that they can either monitor progress or collaborate on the development.

Tell me again WHY I should use Postman workspaces?

Why workspaces are cool:

Personal organization

If your personal workspace is getting cluttered, create a new workspace to mirror your personal workflow in a more granular fashion.

Team organization

Similarly, create new workspaces to mirror your team’s workflow. These can be permanent workspaces aligned by function, product or project, or partner as mentioned above. These can also be temporary workspaces for temporary projects and activities.

Source of Truth

Teams need a single source of truth for their APIs, and workspaces can give a team or sub-team confidence that they’re working off the latest versions of their Postman collections, and know that their changes are being synced in real time.

Team permissions

Team workspaces are read-only by default. You control the edit and view permissions for collections and all of their associated elements by giving edit capabilities to the entire team or only specified individuals on your team.

Discovery

It’s a common scenario that someone will be working on something that the broader team knows nothing about. If there are collections shared in a common workspace, this allows all team members to understand the scope of a project and see those elements more clearly.

Search for APIs

For Postman Pro and Enterprise users, you can index and find all your APIs by searching across not only workspaces, but also collections, folders, requests, and saved responses.

Up-to-date Activity Feed

View an activity feed of CUD (Create, Update, Delete) operations within a collection. Stay on top of who updated a collection, what the updates were, and when they were completed.

Real time debugging with History

When team members join a workspace, even the request history is a shared entity. Everyone who is part of that workspace can see the most recent requests sent, and observe the behavior in their own instances of Postman in real time. Previously, you might have discovered the bug, exported a cURL request from Postman, sent it over for someone else to load it up in their own instance of Postman.

---

Is your team using Postman workspaces? Let us know how in the comments below. And stay tuned for a sneak peek into how the Postman team engineered workspaces.