Public Workspaces: Why We Created Them and What You Can Do with Them

Let’s start with a bit of background.

Here at Postman, we’ve always been obsessed with successful API calls. Why, you ask? A successful API call ensures that something that you’ve built is working; it gives you access to a system that was beyond your reach, helps you see data that you couldn’t see before, or helps you execute an action that you couldn’t do before. Successful API calls mean working software, productive teams, and successful companies—and conversely, any failure in an API call prevents you from making progress.

Successful API calls have tremendous power. That’s why we’re obsessed with them.

In fact, one way to see Postman’s history is as a continuous evolution toward better ways to make successful API calls.

It started with the Postman interface itself. The Postman interface simplifies what you need to know to execute an API call; in short, it allows you to do something that previously was only possible through memorizing command-line flags or knowing a programming language. Mistakes that are common within a command line or written code are eliminated because the interface provides well-defined boundaries to work in. The interface also translates what you mean into syntax that the computer understands, very much like how a higher-level programming language allows developers to more easily write machine-language code that a CPU understands.

When we saw people being successful with the simplicity of the Postman interface, we wondered, “How can we simplify it even more?” Well, the answer was in Postman Collections. When collections were introduced, they allowed anyone making API calls to eliminate yet another potential stumbling block: You don’t even need to remember what elements are required for your API call. If somebody has created a Postman Collection, that work has already been done for you by someone else. And now, you can use this shared knowledge to make a successful API call even faster. These collections can even include documentation to tell you what you can do, and tests to help verify whether things went well.

After we invented the idea of a Postman Collection, our users started sharing collections with each other, and soon they wanted us to make that process of sharing even faster. Not only were they sharing collections with their immediate peers (i.e., their team), but they were also sharing collections with the outside world (i.e., their community) if they had public APIs.

Being able to share collections easily within teams gave rise to Postman workspaces. Workspaces for Postman helped teams collaborate more effectively and become faster in API development, testing, deployment, and the hundreds of other tasks that are part of the process of producing and consuming an API. Workspaces also helped us monetize the product: as teams using workspaces became faster and their APIs became better, they were willing to pay for that value.

However, collections aren’t the only abstraction that we thought about. Since Postman started in 2012, there has been a significant and parallel movement in the global API community to drive the API lifecycle through well-defined specifications—the most prominent of them being the OpenAPI Specification. Postman users began importing these specifications as collections and then driving the rest of the API lifecycle in Postman. But still, the process was overly complicated.

We realized we could make this process simpler and truly define an API-first development workflow within workspaces. Hence, we invented the API abstraction—along with Postman’s API Builder that we created to help you work with the abstraction—which gives you the ability to write, validate, and synchronize your chosen specification with your code repository; well-defined specifications can now be used to generate precise collections that help everyone make better code, docs, tests, and monitors. Postman workspaces are designed to package this entire workflow so your team is better at producing and consuming APIs.

Not only that, workspaces also provide annotation and commenting capabilities that allow two-way feedback between producers and consumers to drive even more successful outcomes. An API call not working? Simply bring someone in to help you out and work with them without losing context.

Sharing your work with the outside world is more complicated, though. The level of trust that you have within your team can’t be assumed for people in the outside world. However, there is an inherent need to collaborate with people outside a company that exists because of public APIs. While Postman users could always export collections through files, we made that process a bit easier with our API documentation tool that allowed publishers to create a web page that renders the collection with code samples. We also created the Run in Postman button that allows a publisher to embed the collection inside their own web page. Today hundreds of thousands of APIs use either of these two mechanisms to ensure that their consumers can make successful API calls.

Unfortunately, API documentation within Postman—or anywhere else—does not have two-way communication. It also excludes a lot of other key parts of the workflow that I mentioned above. Knowing from our experience of making teams productive, we wondered whether we could make this even better.

Earlier this year, we set about redefining what public collaboration would mean for APIs. It meant a fundamental rearchitecting of our product and our platform. Along the way, we’ve made Postman faster, the user interface smoother, and made hundreds of small changes ultimately geared towards ensuring a beautiful collaborative experience for people to be successful with APIs.

Introducing Public Workspaces

First, what is a public workspace? A public workspace is a “place” for your API artifacts, and also a place for API producers and API consumers to coexist and work together. (Read our blog post announcing Postman public workspaces here.) The key difference here is that the API consumer can be anyone in the world: A public workspace exists at a URL (more on that below) that allows anyone to see what’s in the workspace—even if they don’t have a Postman account. A free Postman account allows the consumer to actually interact with the workspace and establish a two-way dialog with the producer.

A public workspace is not opinionated about what can be in it. A workspace could be published by a company, an open-source project, a non-profit, or by anyone who wants to bring people together in a single place for a shared interest in a specific set of APIs. Let’s look at seven key features of the Postman API Platform that make all of this possible and collectively deliver what we call the “massively multiplayer” experience you get with public workspaces.

1. Identity

Just like you have a public GitHub or a public Twitter account, you can create a public identity on Postman.com. Public identities are available at postman.com/username. For example, my profile is at postman.com/a85, and Postman’s profile is at postman.com/postman. Your public identity can be toggled on inside your settings, and that identity is what you use to interact with the Postman universe.

2. Unlimited free collaboration

Anyone can create a public workspace for free on Postman and invite as many people as they want within it (this is definitely one of the principal reasons we call public workspaces a “massively multiplayer” experience). We don’t charge for public workspaces. It’s completely free! Public workspaces exist at postman.com/your-identity/workspace/workspace-name. You can check out Postman’s workspace—and all of the outstanding collections it contains that can help you accomplish many of your API workflows programmatically—here: https://www.postman.com/postman/workspace/postman-public-workspace/overview.

3. Commenting

With a Postman account, you can comment on collections or APIs or even specific parts of a request inside a collection. Want to point out something that can be improved? You can make contextual comments to keep discussions well-directed and useful. If you are an API publisher, this is an opportunity to learn what you can do better for your API. This commenting capability really comes to life with the large-scale collaboration of public workspaces.

4. Forking and pull requests

Collections inside a workspace can be “forked” (i.e., you can create a copy of that collection while still maintaining a link to its parent, and then you can work on that collection in your own workspace in your account). This allows you to consume APIs without disturbing the parent collection. We’ll soon be enabling public “pull requests” that will allow you to contribute back to that original collection. If you’ve ever used GitHub or any other source control system, you’ll be familiar with these operations. Postman workspaces allow you to do this without any prior knowledge of git commands or GitHub and you can use these features easily. Postman also automatically creates versions of collections without needing to commit, so you can always be assured that everything that you do is backed up.

5. Watching

If you are dependent on an API, it’s critical that you are aware when it changes. Every API built in Postman has a “Watch” button now. If you click that button, you will be notified of changes to the API schema with a meaningful difference shown to you about those changes so you can take action at your end.

6. Searching

Postman now has a powerful API search engine right at the center of the new interface. The engine searches through the entire universe of APIs accessible to you. This includes your data, your team’s data, and the data on the Postman API Network. You can filter your results according to workspaces, collections, or APIs. If you are an API publisher, this is where millions of consumers will find your API or your public workspace. And because consumers can fork and watch, you now have the ability to stay continuously in touch with your consumers once they’ve discovered your API or workspace.

7. Exploring

Not sure exactly what you’re looking for? You can explore the Postman Public API Network at any time to find an extraordinary range of public workspaces, APIs, and collections curated by Postman. We constantly feature top workspaces and APIs on the home page, and we’ll also be adding some special categories in the coming days.

Conclusion

So those are seven key Postman features that underpin the massively multiplayer API experience you get with public workspaces. We have many more things in the works that will make the experience even bigger.

APIs are a fundamental building block of modern software. We believe public workspaces are a fundamental change in the way public APIs will be built and consumed. Public workspaces will provide a shared global place for human knowledge about APIs, and ultimately help everyone be more successful with APIs.

Public workspaces are now in open beta, so we would love your feedback on what we can do better. Feel free to reach out to us on our own Postman public workspace, GitHub, Twitter, or in the comments section below.