13. Designing APIs (OpenAPI / Swagger)

Historically, developers built APIs *first*, and then wrote documentation and test suites as an afterthought. This often resulted in disjointed interfaces. Modern development organizations adopt the **API-First Design** methodology—specifying the API contract *before* writing code. The **Postman API Builder** is the central design studio to manage this cycle.

What is the Postman API Builder?

The API Builder allows you to design, build, test, version, and deploy APIs from a centralized dashboard. Instead of managing collections in isolation, you create a parent **API Entity** in Postman and link your schemas, tests, mock servers, and environments to it.

Authoring OpenAPI Schemas

Postman includes a fully-functional Web IDE to write API contracts using industry-standard formats like **OpenAPI 3.0 (Swagger)**, **RAML**, or **GraphQL schemas**. Below is a simple OpenAPI 3.0 contract written in YAML format:

openapi: 3.0.3
info:
  title: User Accounts API
  version: 1.0.0
  description: Simple API first schema designed inside Postman
paths:
  /users:
    get:
      summary: Retrieve all active users
      responses:
        '200':
          description: Successful execution
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    email:
                      type: string

Enforcing Schema Validation

Once you have authored your OpenAPI schema, how do you verify that your actual collections and backend servers match this contract? Postman provides **Schema Validation**:

• You can generate a Postman Collection directly from your OpenAPI schema. Postman will automatically configure the requests, folders, paths, and examples to match the definition perfectly.
• If you edit the schema later (e.g. adding a new query parameter), Postman will display a **Sync Alert**. Click **Validate Collection** to view a visual diff showing exactly where your collection differs from your schema.
• With one click, you can pull the schema modifications into your collections, ensuring that your test suites stay perfectly synchronized with your API specifications.

API Versioning

APIs evolve. You cannot change endpoints without breaking existing mobile or web applications. The API Builder handles **API Versioning**:

• You can create distinct versions of your API contract (e.g., `v1.0.0`, `v1.1.0`, `v2.0.0-beta`).
• Maintain parallel mock servers and collections for separate versions, allowing frontend teams to safely integrate new changes without disrupting stable production systems.
• Track history changes and release logs directly in the versions dashboard.