The ultimate guide to setting up team workspaces

In the world of API development, collaboration is key. With multiple moving pieces and stakeholders, organization, transparency, and communication are vital to successful team collaboration. Keeping this in mind, Postman built team workspaces to help you and your team stay organized, maintain a single source of truth, and discuss your work with ease.

In this guide, we’ll explore how new teams can hit the ground running with team workspaces. We’ve covered everything you need to know to set your team workspaces up for success, including actionable steps, real-world examples, and tips to accelerate this process.

Let’s get started.

What are team workspaces?

Team workspaces in Postman are a shared space for teams to design, develop, and test APIs together. They serve as central hubs for project management, allowing teams to seamlessly organize, share, and collaborate on API projects and their related entities, including collections, requests, and environments.

5 benefits of team workspaces

Team workspaces help you:

1. Organize your work

A team workspace gives you a dedicated space for everything you need to complete your API testing and development workflows. No more looking around for authentication keys for different stages, importing and exporting files, and working disconnectedly.

2. Collaborate with context

Instead of jumping between different collaboration tools and Postman, you can now use workspaces to have conversations about requests, environments, etc., right from within Postman.

3. Onboard new teammates faster

With a team workspace, new team joiners can access everything they need to get up to speed with your team’s resources and initiatives more quickly.

4. Improve security

Ensure only the required people can view and edit team resources by controlling access to your workspace and its components with role-based permissions. Plus, team workspaces also enable you to keep track of changes with activity feeds.

5. Increase efficiency

Advanced Postman features like APIs, mocks, and monitors in team workspaces go a long way in helping you streamline your API development and testing processes and improve efficiency.

How do you set up a team workspace?

Setting up a team workspace is a fairly simple process when you have your team’s goals and structure charted out. We’ve broken down this process into the following four simple steps and covered all the nitty gritty that goes into enriching team workspaces with the right resources.

Step 1. Create and organize your team

First things first, to be able to create a team workspace, you need to have a team. So, if you don’t have one yet, you can create a team either through the home page or from the menu on the right corner of your Postman app:

Here are a few best practices to keep in mind while creating your team in Postman:

1. Create a sense of identity

Give your team a meaningful name that reflects your company. Here are some examples in the Public API Network:

2. Optimize your team URL

Customize the team URL by including your domain or team’s name to make it easier for your team to remember and sign in later:

3. Decide who to invite

Your team’s goal and your organization’s structure and requirements can help you decide who should be on the team. On a high level, you can consider including:

• Developers who are actively involved in creating and testing APIs.
• Testers and quality assurance personnel who can create and run tests.
• Technical writers if your team requires comprehensive API documentation.
• Project managers or product owners who need visibility into API development progress.
• Stakeholders or decision-makers who need to stay informed about API development.
• DevOps engineers involved in automating API deployment and managing CI/CD pipelines.
• Infrastructure engineers who design, build, and maintain infrastructure components.

4. Invite the right people

Once you’ve decided who should be a part of your Postman team, you need to invite them and define their Postman roles accordingly. Here are a few key Postman roles you can consider, along with the Postman subscription plans that include them:

• Admin (All plans)
• Billing (All plans)
• Developer (All plans)
• Guest (External user, all plans)
• Flows Editor (Professional annual plans only)

You can also assign the following roles that are specific to workspaces and collections:

• Admins: can configure team settings, manage roles, and invite new members.
• Developers: can create and modify API collections and requests.
• Viewers: can review API documentation and monitor progress without making changes.

With your team now in place, let’s next look at how to structure and set up team workspaces.

Step 2. Create team workspaces

Once you’ve created your team, a team workspace gets created by default. In addition to this, you can create more team workspaces to suit your team’s structure, workflows, and preferences.

Creating different workspaces for different requirements helps ensure your team remains organized and members can access the resources needed to work and collaborate.

Here are a few different ways in which you can structure team workspaces:

By projects

Organize your workspaces by specific projects or initiatives your team is working on. This structure allows each project team to have its dedicated workspace for efficient collaboration and management.

For example, if you’re developing a mobile app, create a workspace named “Mobile App Development” and store all APIs, environments, and tests related to the app in that workspace. Similarly, you can create workspaces for web app development, integrations, etc.

Recommended for: Teams working on multiple distinct projects or initiatives.

By environments

If your team is organized by different squads for environments like development, testing, and production, then group your workspaces by these environments. This ensures that team members work with the correct API endpoints and settings for each environment.

Recommended for: Teams that need to manage APIs and tests across different development stages.

By squads or departments

In case your organization is divided into squads, departments, or teams that work on different APIs and projects, you can create separate workspaces for each group. This approach enables each group to have its own workspace for focused collaboration.

For instance, you can create workspaces like “Backend Team”, “Frontend Team”, or “Marketing Department”, and create resources accordingly.

Recommended for: Larger organizations with distinct squads, departments, or teams.

By features/modules

Does your team work on a project that involves multiple features or modules? Then, you can organize your workspaces based on these components to maintain focus and prevent clutter.

Say, for an e-commerce website, you can create workspaces for “Product Catalog,” “Shopping Cart,” and “Payment Gateway” to separate API development and testing for each feature.

Recommended for: Teams working on complex projects with multiple interconnected features or modules.

 By various needs/use cases

Create workspaces tailored to specific needs or use cases, such as cloud infrastructure management, API testing, or engineering onboarding. This approach ensures that specialized teams have dedicated workspaces for their unique tasks.

Recommended for: Teams with diverse requirements, such as API testing, API security, API development, and more.

Pro tip: You can use workspace templates to speed up the process of creating workspaces.

Step 3: Create workspace resources

Once you’ve created team workspaces, you can set them up with specific resources that you need to use in your workflows. These resources include collections, environments, APIs, mocks, monitors, and flows. For now, let’s dive into collections and environments, two of the more commonly used resources.

Postman Collections

A Postman Collection is a set of API requests that are grouped and organized in a logical manner. Collections are at the heart of most API workflows in Postman:

With collections, you can:

• Save and organize requests in an order that makes the most sense to you for easy access and reusability.
• Test your API and request workflows across multiple iterations.
• Share your requests in a click and collaborate with multiple partners.
• Generate API documentation that is easy to share and consume.

Here are some tips to help you structure collections:

• Naming conventions: Use consistent and descriptive naming conventions for your collections. Names should reflect the purpose or functionality of the collection. For example, “User Management API” or “Payment Gateway Testing”.
• Folder hierarchy: Organize your requests into folders within collections. Create folders for different sections or features of your API. For instance, you can have folders like “Authentication,” “User CRUD Operations,” and “Payment Processing.”
• Request ordering: Arrange requests within folders and collections in a logical order, especially if there are dependencies between them. This ensures that test scripts added to the collection execute in the correct sequence.

Pro tip: You can use collection templates to speed up your API design, development, testing, and documentation workflows.

Environments

Environments in Postman are a set of variables that are used to mimic different stages of development like local, beta, production, and more. By setting up environments, your team can swiftly between different setups, ensure consistency, and reduce errors in API requests.

Environments are especially useful when working with different values, URLs, API keys, tokens, and other configuration settings in your API testing and development workflow. By using environments, you can:

• Avoid accidentally exposing API keys and tokens in your requests or collections.
• Reduce the chance of errors due to configuration discrepancies.
• Share consistent environment configurations with your team.

Here are a few tips on how to make the most of environments:

• Environment management: Set up different environments for various stages of your application (e.g., development, staging, production).
• Naming conventions: Adopt a clear naming convention for your variables to reduce ambiguity. Prefix variables with the environment they belong to, such as dev_baseURL or prod_apiKey.
• Protect secrets: Store sensitive data like API keys and tokens as environment variables rather than hardcoding them in requests.

Bonus: pro tips for collaborating in team workspaces

Once you’re done setting up your team and team workspaces, you should be ready to start working on APIs together. Here are a few ways you can kickstart team collaboration.

1. Stay on top of all changes

Keep track of all changes, additions, and edits using activity feeds in workspaces and collections. This serves as an audit log for progress tracking and incident resolution.

2. Use comments to discuss your work

Utilize comments to facilitate discussions, issue debugging, and real-time conversations. Mention teammates on a request or a folder to involve them in discussions effortlessly:

3. Manage multiple API versions efficiently

Use version control to manage multiple versions of an API to prevent conflicts and maintain consistency:

4. Develop in parallel

Like branching and merging on Github, you can fork and merge collections to keep them up to date while enabling developers to work in parallel:

5. Prioritize documentation

Make sure all APIs and collections are well-documented. This way, you can help consumers of your API understand how to work with your API right from the get-go. Creating a culture of documentation can help ensure that everyone has the right context to be successful at all times:

Level up your API collaboration with Postman today

Setting up team workspaces in the Postman API Platform is a fundamental step towards efficient and collaborative API development and testing. By following the steps and best practices listed in this guide, your team will be well on its way to achieving success with Postman.

How are you planning on setting up your team workspaces? Let us know in the comments below!