What Is Postman? API Development Platform Guide

Postman is an API development platform for designing API specifications, sending requests, organizing reusable collections, managing variables, creating mock servers, writing tests, generating documentation, running monitors, and sharing API workflows. Developers often start with Postman as a graphical HTTP client, then connect these assets across design, development, documentation, collaboration, and repeatable validation.

This guide explains the platform and where its major capabilities fit, with an emphasis on request-development workflows. For a hands-on workflow focused specifically on assertions, collection runs, command-line execution, and CI pipelines, use the dedicated Postman API testing automation guide.

What Is Postman Used For?

Postman provides one workspace for several related API tasks:

1. Explore an API: Send a request, inspect headers and bodies, and troubleshoot authentication or payload problems.
2. Save repeatable workflows: Store related requests in collections instead of rebuilding them for each test session.
3. Manage configuration: Use variables and environments for base URLs, identifiers, tokens, and other values that change between deployments.
4. Document examples: Save request and response examples with the collection so teammates can understand expected behavior.
5. Test behavior: Add pre-request and post-response scripts, then run the collection manually or from an automation tool.
6. Mock unfinished endpoints: Return saved examples from a mock server while client and backend work proceed in parallel.
7. Design an API contract: Create or import a specification, validate its syntax, and connect it to collections and tests.
8. Generate and publish documentation: Build documentation from collections or API specifications, add explanatory context, and publish it when appropriate.
9. Monitor API workflows: Run selected collections and tests on a schedule or by CLI trigger to track health, failures, and response times.

The official Postman documentation is the source of truth for currently supported protocols, plan limits, and product behavior. See its guidance for API specifications, API documentation, and monitors for those platform areas.

Send Your First API Request

A Postman request combines the same elements used by any HTTP client:

• an HTTP method such as GET, POST, PUT, PATCH, or DELETE;
• a URL and optional query parameters;
• request headers, including authentication and content type;
• an optional request body;
• scripts that run before the request or after the response.

For example, a request to retrieve a user could use:

GET {{baseUrl}}/users/{{userId}}
Authorization: Bearer {{accessToken}}

The variables keep deployment-specific values out of the saved request. After the server responds, Postman displays the status, headers, body, cookies, and timing information for inspection.

If you are learning the underlying protocol concepts, see HTTP methods in APIs and RESTful API best practices.

Organize Requests with Collections

A collection is a reusable group of requests and related configuration. Teams commonly organize collections by API, service, or user workflow.

Store API
├── Authentication
│   └── POST /login
├── Products
│   ├── GET /products
│   └── GET /products/:id
└── Orders
    ├── POST /orders
    └── GET /orders/:id

Collections can contain folders, descriptions, variables, examples, and scripts. That makes them useful as both a working request library and an executable record of how an API is expected to behave.

Keep a collection focused on one bounded domain. A smaller collection is easier to review, run, and maintain than a single workspace containing unrelated endpoints.

Manage Deployments with Environments and Variables

An environment stores values that belong to one deployment context:

Requests reference a variable with double curly braces, such as {{baseUrl}}/orders. Switching the active environment changes the resolved value without changing the request definition.

Do not commit real credentials in exported collections or environment files. Use Postman Vault or secure variables in Postman, and inject secrets from the CI secret store at runtime.

Add Logic and Tests with Scripts

Postman supports scripts that run before a request and after a response. Pre-request scripts can create dynamic values or prepare authentication. Post-response scripts can assert the status, inspect response data, and store values for later requests.

pm.test("Returns a successful response", () => {
  pm.response.to.have.status(200);
});

pm.test("Returns a user identifier", () => {
  const body = pm.response.json();
  pm.expect(body).to.have.property("id");
});

According to the Postman scripting documentation, these scripts use the Postman Sandbox and can be attached at collection, folder, or request level. Use collection-level scripts for behavior that truly applies to every child request; keep endpoint-specific assertions with the request they validate.

Testing is only one part of the Postman platform. The Postman API testing automation guide covers test-suite structure, data-driven runs, Postman CLI, Newman compatibility, and CI failure handling in detail.

Use Mock Servers for Parallel Development

A mock server returns responses based on examples saved with a collection. It can help when a client team needs to integrate before the production backend exists.

A typical workflow is:

1. Agree on the request and response contract.
2. Save representative examples with the collection.
3. Create a mock server from those examples.
4. Point the client at the mock URL during development.
5. Switch the environment's baseUrl to the real service when it is available.

Mocks validate a client against agreed examples; they do not prove that the real backend implements the contract. Add contract and integration tests before release.

Use Postman with an API Gateway

Postman acts as a client, while an API gateway enforces runtime policies between clients and backend services. A team can use Postman to verify observable gateway behavior such as:

• an unauthenticated request returns the expected authentication error;
• a routed request reaches the intended API version or upstream;
• a transformed request or response matches the published contract;
• a request over the configured rate limit receives the expected response.

The test must match the gateway's actual configuration. Do not assume a specific status code, response header, or retry behavior without checking the policy in use.

Postman vs curl

Postman and curl can send many of the same requests, but their working models differ.

Use curl when a compact command is enough. Use Postman when the request belongs to a shared, repeatable API workflow.

Postman Workflow Best Practices

1. Organize collections by API domain or workflow. Avoid one oversized collection for unrelated services.
2. Keep base URLs and deployment values in environments. Do not duplicate requests for development and staging.
3. Keep secrets out of exported files. Inject them at runtime or use protected secret storage.
4. Write descriptions and save representative examples. Make the collection understandable without tribal knowledge.
5. Place scripts at the narrowest useful scope. A global script is harder to reason about than a request-level assertion.
6. Review generated or imported requests. Importing an OpenAPI description creates a starting point, not a complete test strategy.
7. Separate exploration from release gates. A request that works once in the GUI is not yet a deterministic CI test.

FAQ

Is Postman only an API testing tool?

No. Testing is one capability. Postman also supports request exploration, collections, variables, examples, mock servers, documentation workflows, and team collaboration.

What is a Postman Collection?

A collection is a group of saved requests with optional folders, descriptions, examples, variables, and scripts. It can serve as a reusable workflow or a test suite, depending on how it is structured.

Can Postman test an API gateway?

Yes. Send requests through the gateway and assert externally visible behavior. Keep those assertions aligned with the configured authentication, routing, transformation, and traffic policies.

How do I automate Postman API tests?

Turn repeatable requests into a collection, add deterministic post-response assertions, separate configuration from secrets, and run the collection with the Postman CLI or a compatible Newman workflow. Follow the Postman API testing automation guide for the complete process.

Related Guides

• Postman API Testing Automation
• OpenAPI Specification
• RESTful API Best Practices
• API Security Testing Tools
• Postman vs Katalon