Learning to Collaborate on API Development with Postman

API development is a big part of what I love about software. Whether it's building integrations or crafting APIs for decoupled web applications, it's usually just me and the code.

Most of the time, I work as a solo API developer. Going solo has its perks: fast decisions and full control. But it's a double-edged sword, since keeping everything in my head makes handoffs and delegation tricky. And, going solo limits the size and complexity of projects I can work on. After all, I am just one person.

Postman is my primary tool for API work - sending requests, managing environments, and running tests. I'm familiar with my solo workflow. But I've started to wonder: in a team environment, what more can Postman offer? How might it enhance collaboration and streamline the dev process?

To explore these questions, I started working on an example API, which I call "X Nihilo."

Example API: X Nihilo

X Nihilo helps you generate 280-character tweets based on parameters you store or send. You provide a topic, a goal, a description of the tone to take, and a description of the audience. Behind the scenes, the API will send a request to OpenAI's API for text completion, which will assist in generating the tweet.

In addition, you can save the strings you use for tone and audience, then reuse them in subsequent tweet requests.

Let's walk through my basic API dev workflow.

Going at it alone: my solo workflow

The first step in my workflow is to design the API and write up an OpenAPI spec. In Postman, I created a new API, and then I started a new API definition.

After some thinking (and working directly with ChatGPT, which was great for generating an initial OpenAPI spec based on my descriptions), I had my spec written:

With my OpenAPI spec in place, I came to a fork in the road. Should I set up a mock server and some example requests and responses to show what it would look like to interact with this API? Or should I start writing implementation code?

As a solo developer, I can only be an API producer or an API consumer at any given time. So I decided: no need for to build mocks - the consumer in me would have to wait. Let's write some code!

A few moments later…

Using Node.js with Express, and talking to a PostgreSQL database, I had my basic API implemented. Here's a rundown of everything that I needed to build:

• POST /signin takes a username and password, authenticates against records in the database, and then returns a signed JWT which can be used in all subsequent requests.
• POST /generateTweet generates a 280-character (max) tweet. It takes a topic (string) and a goal (string). It also takes either a tone (string) or a toneId (integer ID of a stored tone), along with either an audience (string) or an audienceId (integer ID of a stored audience). Whenever tone and/or audience strings are provided, the API will save these to the database.
• GET /tones returns a list of tone IDs and corresponding strings. GET /audiences does the same for reusable audience strings.
• DELETE /tones takes a tone ID and deletes that tone record. DELETE /audiences does the same for audience records.

After the initial implementation was done, it was time to get back to Postman to start running some requests.

Create an environment with variables

First, I created a new environment, called "Test." I added variables to store my root_url along with a valid username and password.

Create a collection and a request

Then, I created a new collection and added my first request: a POST request to /signin, to try out authentication.

With my API server running in a terminal window, I sent my first request.

Success! I got my token, which I would need in any future requests.

I created a new request, this time to generate a tweet.

I made sure to set the Authorization to use "Bearer Token," and I provided the token that I just received from the previous request.

Here's the response:

It works!

Summing up the solo approach

That's a basic sneak peek into my solo workflow. Of course, I would do a few other things along the way:

• Write a pre-request script to perform a /signin request and then set an environment variable based on the token in the response.
• Create requests for all other endpoints in the OpenAPI spec.
• Write tests for each endpoint, making sure to cover my edge cases.

If I'm working solo, this basic workflow gets me pretty close to the finish line. While that's fine, I know that I'm probably only scratching the surface of available features in Postman. And I know that I would need a lot more from Postman if I was working on a team.

The aha moment: Why consider Postman for teams?

What if I could no longer be a solo API developer for X Nihilo? This could happen due to several reasons:

• X Nihilo grows in size and complexity, and a single API developer is no longer enough to support it.
• X Nihilo is only a small part of a larger API project involving multiple API developers, or maybe even multiple API teams.

Not all of my API projects for clients will be small ones that I can build on my own. At times, I'll need to be part of a team that builds an API. I might even need to lead the API team.

When that happens, I would need to leave my solo mindset behind, and leave my solo way of doing things in Postman. That motivated me to look into Postman's team-related features.

Exploring Postman's team (enterprise) features

Postman has a free tier, and it offers some limited collaboration features, which might be sufficient if you're a small team (meaning: not more than three developers). Postman has additional features as part of its Enterprise Essentials tier. These are great for API teams in larger organizations that use Postman across the board.

Workspace sharing

A workspace lets your teams collaborate on multiple API projects. This is great if you have different teams working on different APIs, but those APIs interact with one another (which is typically the case in larger software organizations).

Workspaces are excellent for enabling real-time collaboration. Team members can edit API documentation, work together on crafting requests or writing tests, and build out a mock server that the entire team can use. As edits are made, they're synced with the entire team in real time.

Version control

While I cared about version control for my code, as a solo API developer, I didn't care much about version control of my Postman collections or environments. If I change something (modify a request, update a test, remove an environment variable), I'm the only one affected. No big deal.

When you work on a team, you definitely want to know when things change. And sometimes you need to roll back changes. Fortunately, for teams using Postman Enterprise, Postman gives you access to a changelog for collections, workspaces, and APIs. You can roll back collections to earlier points in time. As an API developer on a team, you'll need this. Most of the time, it's because Bob screwed up the collection. Sometimes, though, you're Bob.

Role-based access and user organization

Not everybody in a Postman workspace should have the same level of permissions. Some team members are testers, and they just need the ability to send requests and run tests - but not modify them. Others might be designers who are only allowed to modify API definitions.

In Postman, you can assign roles to team members. This affects the kind of access and level of permission that each team member has within a team or workspace.

Teams can also have private workspaces, restricting access from others outside the team.

I also noticed that Postman Enterprise supports "domain capture." This basically means you can set up all the users in your organization by giving access to everyone from the (for example) mycompany.biz domain.

Inline comments and discussions

Postman does have one collaboration feature which is available on all its plans, not just its Enterprise Essentials. This is the ability for team members to add comments to collections (on folders, requests, examples, or pull requests). Being able to comment and discuss directly in Postman is huge for team API development. Since most of your team's API dev work will happen in Postman, it makes sense to have your discussion there (instead of in GitHub or some other external service).

Team API development: Postman for the win

Whenever I join a team, I bring the tools that I love using, but I don't really push them on my teammates. I figure they've got their own tools. So, to each their own. But I have a feeling that most API developers have Postman in their toolbelt. It would just be a shame if several API developers on a team all used Postman individually, with a solo mindset and without taking advantage of some of these team features. If they took advantage of Postman Enterprise features, they would get…

Increased efficiency

In a shared workspace, you get to start with the shared API definition. Whenever a team member edits the definition (or documentation or tests or environments), the edits sync up, and everybody has the latest and greatest.

Everybody works off the same set of requests in a collection, and everybody has access to all the tests that will be used. All of these conveniences will improve a team's efficiency, which in turn will skyrocket their development velocity.

Fewer misunderstandings

When everybody is working from the same source of truth (your workspace), and they can make comments and converse within the tool they're using for development, this will lead to fewer misunderstandings. Your team won't lose time to confusion over whether that endpoint was supposed to take query params or path params. Everything will be clear.

Key takeaway

I didn't know that Postman was for teams and enterprises. Now that I know, here's my big takeaway: Team players use tools that are good for the team.

Postman has been great for me when I'm a solo API developer. Fortunately, it also has the features that would make it great for me when I'm on an API dev team. For me, that's real-time sync of edits within collections, changelogs and version control, and granular permissions for access. Now, I'm excited to take on larger API projects with larger teams.

Happy coding!