Postman Best Practices

Understanding what you're building: how API types drive workspace organization

Team collaboration and API work are centralized in a workspace. The type of API you build shapes how your team works together, how you apply governance, and how you measure success.

Before you decide how to organize your workspaces, start by understanding what kind of API you’re creating. Some APIs are built for a single application and team, while others are designed for many consumers across your organization or external partners. This distinction defines how you structure workspaces, share artifacts, and scale collaboration from rapid team delivery to organization-wide or public adoption.

App-specific APIs

An app-specific API is built for a single consumer, such as a specific UI, mobile app, or internal integration. These APIs are often developed within a single team or monolithic codebase to meet immediate project needs and are tightly coupled to the consuming application. Think of a backend service built to power your checkout page, or a microservice that only your mobile app calls. Use app-specific APIs for fast iteration and targeted functionality before promoting shared endpoints into reusable APIs that can serve multiple teams.

Characteristics of app-specific APIs:

Built for a single consumer at the time of development
Backend and frontend teams work in tight coordination to meet UI-driven requirements
Requirements flow directly from UI or business logic rather than from shared API contracts
Changes happen quickly within the team, often without formal versioning or review
Testing occurs primarily through the UI, not through dedicated API test suites
Extensive public-facing documentation may not be required since consumers often have access to the codebase and can infer behavior directly.

Reusable APIs

A reusable API is designed for multiple independent consumers across teams, partners, or external developers. These APIs are self-service, meaning other teams can discover, understand, and integrate them without synchronous collaboration with the producer. They emphasize strong specifications, complete documentation, and consistent governance because they must reliably serve many consumers over time. Think of an authentication service used across your company, a payments API offered to partners, or a public API that powers your developer ecosystem. Use reusable APIs when you need stable, scalable building blocks that others can adopt and extend without depending on your team.

Characteristics of reusable APIs:

Designed for multiple consumers, including internal teams, partners, or external developers
Enable self-service discovery and integration through clear documentation and accessible endpoints
Include comprehensive reference docs, examples, and onboarding flows to reduce dependency on the producer team
Follow consistent architectural standards (REST, GraphQL, or async patterns) to ensure predictable behavior
Implement versioning and structured change management to support continuous evolution
Maintain backward compatibility to protect existing integrations and reduce migration friction
Built with external consumers in mind, including considerations for security, compliance, and performance at scale

Why this distinction matters for workspace organization

Different API types require different collaboration patterns, and Postman workspaces provide the structure to support them.

App-specific APIs are best managed in focused team workspaces, where backend and frontend developers can iterate quickly and communicate directly with each other. These workspaces benefit from lightweight processes, integrated testing, and rapid feedback loops. Because the APIs are tightly coupled to a single app, visibility can stay limited to the immediate team. Adding more structure here would slow delivery without adding real value.

Reusable APIs require broader visibility and stronger governance. These APIs live in discovery workspaces where other teams can explore, test, and adopt them. When shared externally, they often connect to Partner Workspaces or public workspaces. As more consumers depend on them, maintaining trust through consistent documentation, change management, and versioning becomes essential. Well-organized workspaces prevent breaking changes, duplicate effort, and the loss of institutional knowledge, ensuring that every API remains discoverable, testable, and trusted.

API maturity and workspace strategy

Organizing workspaces around API maturity ensures that each API type receives the optimal balance of speed, structure, and visibility.

Level 1: Primarily app-specific APIs
Workspaces are organized around products or projects. They prioritize speed and proximity over visibility or governance.
Level 2: First reusable APIs emerging
Teams start designing APIs for broader use. Workspaces expand to include discovery and platform spaces that enable sharing, review, and feedback.
Level 3: Reusable APIs as a common platform
Reusable APIs become central to development. Platform teams manage dedicated workspaces, enforce governance, and publish to the Private API Network for internal discovery and to Partner Workspaces or public workspaces for external ecosystems.

When workspace organization mirrors API maturity, collaboration stays efficient, reuse increases, and governance scales naturally without slowing down innovation.

Find out how your API practices measure up by taking our 5-minute API Maturity Assessment →

Workspaces and collaboration models

Workspaces reflect different collaboration intents: individual development work, team collaboration, internal sharing, and external partnerships. Recognizing these intents is key, as they shape how you’ll organize your Postman setup.

Each workspace type serves a specific collaboration need. Understanding when to use each one helps you organize your Postman setup around how your teams actually work together.

Postman offers three workspace types designed to support different collaboration and sharing needs:

Internal workspaces

Internal workspaces support collaboration within your organization. Teams often set them up using different sharing models and usage patterns, such as:

Developer workspace: A space where engineers start building and testing APIs. These are often private or shared with another engineer and are used for rapid iteration and experimentation. Use developer workspaces for early-stage work before moving to team spaces.
Team workspace: A dedicated space for a squad, product area, or function within your organization. These serve as the authoritative source for your team’s APIs, tests, and documentation. A team workspace is where reusable, company-wide APIs are published for discoverability and reusability across teams.
Design workspace: A collaborative space focused on API design and specification work. Design workspaces are used for defining API contracts, gathering requirements, and iterating on API schemas before development begins. These often serve as the upstream source for implementation work.
Discovery workspace: A workspace created by teams that build reusable APIs for consumption across the organization. Discovery workspaces are where teams publish APIs they create for other teams to discover and fork into their own team workspaces.
Temporary project workspace: A short-term workspace created for cross-functional collaboration on drafts, experiments, or early-stage initiatives before work is moved to more permanent team or discovery spaces.

Partner Workspaces

Partner workspaces are designed for collaboration with trusted external teams such as partners or vendors. They allow controlled access to APIs and resources to support integrations and shared services while maintaining security and governance.

Public workspaces

Public workspaces are intended for open APIs shared with the broader developer community. They enable public discovery, consumption, and contribution to your APIs, fostering community engagement and transparency.

Ready to get hands-on? Create a workspace in Postman →

Types of APIs, Workspaces, and Collaboration Models