POSTMAN BEST PRACTICES

API Governance

Building quality APIs has never been more important. At Postman, we believe being API-first is the key to innovation in the AI era. We built Postman Best Practices to share the foundational ideas Postman is built on and enable you to do your best work.

When teams prioritize speed over consistency, endpoints behave inconsistently, schemas lack validation, and backend and frontend teams experience constant friction.

This chapter provides a systematic approach to API governance that catches common issues early, maintains consistency across consumers, and scales governance standards as your APIs mature from rapid prototypes to reliable platforms.

Abhinav Asthana

Abhinav Asthana

Postman CEO and Co-founder

Ankit Sobti

Ankit Sobti

Postman Field CTO and Co-founder

When teams build APIs for a single app or integration, the priority is usually speed. Specs are kept light, feedback loops are short, and changes happen fast. But this speed often comes at a cost: endpoints might be inconsistent, schemas may lack validation, and details aren’t always documented clearly enough for the frontend to keep moving without delays. Small gaps like these lead to rework, late-breaking bugs, and friction between teams.

Postman’s governance tools help reduce friction by catching common issues early, keeping backend and frontend teams aligned, and ensuring APIs stay reliable.

Governance for app-specific APIs

When you build an app-specific API, you’re typically building for a single consumer, such as a specific UI or integration. Speed matters more than perfect documentation, but inconsistent patterns and missing validation lead to bugs and rework. Developers might handle errors differently, frontend teams can encounter delays while waiting for accurate endpoint details, and schema mismatches may be discovered too late in the process.

These app-specific APIs are developed quickly to meet project demands. The API specification is often minimal and utility-driven, sometimes generated post-implementation to support gateway configuration, authentication, and rate-limiting tasks. Since there is typically only one consumer, feedback loops are short and changes happen quickly.

  • Set up workspaces to enable backend and frontend teams to iterate quickly and collaborate in real time.
  • Use collections to prototype APIs, run tests, mock endpoints, set up monitors, and share behavior across backend and frontend teams.
  • Enrich collections with type information to add structured request and response formats that enhance clarity even before writing formal specifications.
  • Apply lightweight governance rules at the workspace level that catch the most common issues, such as schema validation, required fields, and basic security checks.
  • Store finalized specs in Spec Hub as the centralized deployment reference, using inline annotations to validate readiness at the spec level.
  • Integrate validation into your CI/CD pipeline to catch problems before they reach staging.

Ready to set up lightweight governance for rapid development? Get started with API governance.

API Governance for App-Specific APIs Diagram.

Governance for reusable APIs

Reusable APIs require stricter governance because inconsistencies multiply across every consumer. Unlike app-specific APIs, they prioritize scale and long-term maintainability.

  • Set up workspaces to onboard internal teams, partners, or external developers via shared typed collections, mock servers, documentation, and change management.
  • Design APIs in Spec Hub with comprehensive OpenAPI 3.0 or AsyncAPI 2.0 specifications, or generate specifications from a consumer-validated collection.
  • Use collections to prototype APIs, run tests, mock endpoints, set up monitors, and share behavior across backend and frontend teams. Even when starting with a spec, generating collections to validate against real usage provides valuable feedback.
  • Enrich collections with type information to add structured request and response formats that enhance clarity even before writing formal specifications.
  • Use the governance rule editor to apply Spectral-based rulesets that define consistent structure, naming conventions, and error handling, and enforce these rules automatically.
  • Store finalized specs in Spec Hub as the centralized deployment reference.
  • Integrate validation into your CI/CD pipeline to ensure continuous compliance.
Transitioning from App-Specific to Reusable APIs. Diagram.

Transitioning from app-specific to reusable APIs

Many organizations start with app-specific APIs and gradually evolve them for broader reuse. APIs that start as quick prototypes can evolve into reliable, well-documented services that multiple teams depend on without disrupting your development velocity.

Postman supports this transformation through a staged governance model:

  1. Identify APIs for broader use: Select APIs that multiple teams could benefit from and move them to dedicated workspaces with stricter governance rules.
  2. Gradually increase standards: Apply lighter governance to app-specific APIs while enforcing comprehensive rules on reusable ones. Teams can evolve APIs at their own pace.
  3. Automate compliance checking: Use Postman CLI to validate APIs against your governance standards in CI/CD pipelines, ensuring quality without manual overhead.
  4. Manage change communication: Use workspace updates to notify consumers about API changes, deprecations, and new features as APIs mature.
Scaling API governance across teams. Diagram.

Governance FAQs

What's the difference between a specification and a collection?

A specification is a formal, structured contract that defines how an API should behave. In Postman, specifications are authored in formats like OpenAPI 3.0 or AsyncAPI 2.0, and server as the single source of truth for an API’s structure, methods, parameters, and models.

A collection is an executable form of one or more APIs used for testing, mocking, and documentation. Specifications define what an API should do; collections show how it behaves in practice. For app-specific APIs, specs are often minimal and generated later in the development cycle. For reusable APIs, specs are rich, well-designed contracts that enable consistency across many consumers.

How do specifications work with collections in development?

Specifications and collections are tightly linked in a continuous feedback loop between design and execution. You can design with a spec, then generate a collection in Postman to test and document, and then continue to refine the spec. Alternatively, you can prototype using a collection, validate its usage, and then generate a specification. This two-way interaction enables seamless workflows where design and execution stay aligned throughout development.

How do specifications and governance differ for app-specific and reusable APIs?

For app-specific APIs, specifications are minimal and utility-driven, often generated post-implementation for gateway configuration or basic security checks. Governance is lightweight and focused on execution safety. For reusable APIs, specifications are core artifacts designed from the outset with thoughtful governance, ensuring shared design language, standardized naming, and consistent error handling across many consumers.

How does Spec Hub connect with collaboration through collections and workspaces?

Spec Hub is the central system in Postman for managing API specifications, serving as the source of truth for API structure. Specs in Spec Hub link to collections that provide the live, executable interface for testing, mocking, and sharing. These collections live in workspaces where cross-functional teams can collaborate in real time, ensuring design and usage stay synchronized.

How do you store and manage specifications in Spec Hub?

Specifications are stored in Spec Hub within workspaces, where they're discoverable and shareable across teams. You can create or import specs in OpenAPI 3.0 or AsyncAPI 2.0 formats. Governance rulesets can be applied account-wide or scoped to specific workspaces. Collections can be generated from specs to support documentation, testing, and mocking workflows.

How are specifications evaluated against design rules?

Postman uses governance rulesets powered by Spectral to enforce standards like naming conventions, required auth methods, and response formats. These rulesets can be attached to workspaces, run automatically or manually via CLI, and visualized through inline annotations and governance reports. Different rulesets can be applied to different workspace groups.

What kind of reports are available for reviewing specifications?

Postman provides spec-level reports with inline annotations for immediate developer feedback, and overview reports for platform teams showing cross-spec rule results, coverage metrics, and time-based trends. For app-specific APIs, reports validate gateway readiness. For reusable APIs, they serve as quality gates ensuring specs meet organization-wide standards.