Postman’s API Design-First approach flips the traditional "code first" development cycle, forcing you to think about the API’s contract before writing a single line of implementation code.
Let’s see this in action. Imagine we’re designing a simple API to manage widgets.
First, we define our API contract using OpenAPI (formerly Swagger). In Postman, we can create a new API definition.
openapi: 3.0.0
info:
title: Widget API
version: 1.0.0
servers:
- url: http://localhost:3000/api/v1
paths:
/widgets:
get:
summary: Get a list of all widgets
responses:
'200':
description: A list of widgets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Widget'
post:
summary: Create a new widget
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetInput'
responses:
'201':
description: Widget created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Widget'
/widgets/{widgetId}:
get:
summary: Get a specific widget by ID
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: Widget found
content:
application/json:
schema:
$ref: '#/components/schemas/Widget'
components:
schemas:
Widget:
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
description:
type: string
required:
- name
WidgetInput:
type: object
properties:
name:
type: string
description:
type: string
required:
- name
In Postman, you’d create this as an "API" object. From this definition, Postman can automatically generate mock servers, documentation, and even boilerplate code for your backend implementation.
Now, let’s spin up a mock server based on this OpenAPI definition. In Postman, navigate to your API, click "Create Mock Server," and select the "Mock Server URL" associated with your API. Postman provides a URL like https://<mock-server-id>.mock.pstmn.io. When you send a GET request to /widgets on this mock server, Postman will return a 200 OK with an empty array (or a default example if you’d provided one in the OpenAPI spec). Sending a POST to /widgets will return a 201 Created with a mock id.
This is where the "design-first" magic happens. Your frontend developers can start building against this mock server immediately, long before the backend is even started. They know exactly what the request and response payloads will look like because they’re defined in the OpenAPI spec.
The mental model to build is this: the API definition (OpenAPI spec) is the single source of truth. It’s a legally binding contract between the API provider and its consumers. Everything else — documentation, mocks, tests, and even backend code generation — flows from this contract.
Postman provides several levers to control this workflow. You can:
- Define your API contract: Using OpenAPI or RAML.
- Generate Mock Servers: To simulate API responses for frontend development and testing.
- Automate Documentation: Keeping it in sync with your API definition.
- Create API Workspaces: To organize all your API artifacts (definitions, collections, environments, etc.).
- Generate Server Stubs: Boilerplate code for various backend frameworks (Node.js, Python Flask, etc.) directly from your definition.
- Build Automated Tests: To ensure your actual implementation adheres to the contract.
The single most powerful aspect, often overlooked, is how the OpenAPI definition itself becomes a living document that drives the entire development lifecycle, not just an afterthought. It forces clarity and agreement on data structures, endpoints, and behaviors before implementation, preventing costly rework down the line. The readOnly: true property on Widget.id, for instance, tells consumers they shouldn’t send an ID when creating a widget, and the backend implementation should ignore it if they do, while the API consumer knows they’ll receive an ID back after creation.
Once your mock server and documentation are stable, you’ll want to ensure your actual implementation adheres to this contract by writing automated tests.