The API Workflow

You can design your API directly in Postman using the API Builder. By defining your schema in APIs on the left of the Postman app, your specification can act as the single source of truth for your API project. The API Builder supports API-first development by allowing you to generate collections from your schema and build your development and testing from there.

API Builder

You can connect various components of your API development and testing process to your schema, such as collections, documentation, tests, mocks, and monitors. You can also version your APIs in Postman and connect elements to specific versions.

The number of APIs you can create is dependent on your Postman plan.

Creating an API

To access the API Builder, open APIs from the left sidebar in the Postman app. You can open and edit any existing APIs from here—Postman will automatically open the most recent version of an API by default.

Create API

Click Create an API or + New APIyou will need to be signed into your Postman account.

New API

Enter a name for your API—you can rename, delete, or remove it from the workspace using the View more actions (...) menu in the left sidebar.

When you delete an API or remove it from a workspace, the collections, monitors, mocks, and environments linked to it will not be deleted / removed.

Edit API

You can also create APIs from your workspaces dashboard in your web browser by navigating to APIs and clicking Create an API.

You can also version your APIs.

Defining an API

You can define the structure of your API by creating a new schema or importing it from an existing file you can continue editing. You can also generate a collection from the schema.

You can also sync an API spec from a GitHub repository.

Creating a new schema

To create a new schema, click Add Schema and select Create New. The schema editor will open with default options selected.

New Schema

The default schema format is Open API 3.0, with JSON as the default language. To use a different schema type or language, choose it from the dropdown list.

The schema editor provides options to beautify the content, wrap text, copy, and search. When you finish editing your schema, click Save.

Save Schema

Importing a schema

To import an existing schema from a file, click Add Schema, choose Import file, and select the file. You can then edit the schema and save your changes.

Postman currently supports OpenAPI (versions 1.0, 2.0, and 3.0), RAML (0.8 and 1.0), and GraphQL. Your schema can be defined in JSON, YAML, XML, or GraphQL SDL.

Multi-file variants of schemas are currently not supported.

Generating a collection

The Postman API Builder supports API-first development by providing the option to create a Postman collection directly from a schema. Once you have a saved schema, you will see the Generate Collection option:

Schema Editor Options

To create a collection based on your schema, click Generate Collection. You can optionally add the collection as documentation, a test suite, an integration test, or a contract test. The collection will appear in Collections in the left sidebar.

Generate Collection

Developing an API

Once you have a schema in the Postman API Builder, you can develop your API using version tagging, and linking to mock servers, documentation, and environments.

When you add documentation, test suites, mocks, monitors, and environments, only the elements in the current workspace will be visible. If an element is already linked to an API, it will not be visible.

Adding a mock server

You can link mock servers for a collection to an API, by creating a new mock server, or adding / editing an existing one. From the API Builder Develop tab, click Add Mock Server.

Add Mock to Schema

Creating a new mock server

In the Add Mock Server dropdown, select Create new mock server.

Add Mock to Schema

Choose Generate collection from schema to create a mock server on the collection based on the schema. Specify a name and click Generate Collection and Continue.

Mock Generation

Adding an existing mock server

In the Add Mock Server dropdown, select Add existing mock server.

Add Existing Mock

Select a mock server from your workspace and click Add Mock Server. You will only see available mocks in the list. Your mock server will be added to the API.

Mock Added

You can add mocks to specific versions of your API or collection.

Editing a mock server

You can edit existing mock servers from an API by opening the Develop tab then hovering over the server in the Mock Servers section, and selecting the edit button.

Edit Mock from Schema

Your mock will open for editing in the Postman web dashboard.

api edit mock web

You can also copy the URL of your mock server directly to your clipboard by clicking Copy URL.

Adding documentation

You can link the documentation generated from your collections to specific versions of an API.

Add Docs to Schema

In the API > Develop tab, click Add Documentation.

Add Docs to Schema

Select the collection with the documentation you want to link and click Add Documentation. You will only see available collections in the list.

You can add documentation to specific versions of your API. To learn more about versioning and documentation, check out versioning your docs.

Adding an environment

You can link specific environments in your workspaces to specific versions of an API. In the API > Develop tab, click Add environment.

Add Environment to Schema

Select an environment from the list and click Add environment. You will only see available environments in the list.

Add Environment to Schema

Testing an API

You can create collections to use as test suites, integration tests, or contract tests for your API. These collections can be linked to a specific version of your API.

Adding a test suite

You can connect a test suite to any API you have defined in the Postman API Builder. In API > Test tab, click Add Test Suite.

Schema Test Suite

Select a corresponding collection from the list and click Add Test Suite. You will only see available collections in the list.

Add Test Suite to Schema

Adding integration tests

In API > Test, click Add Integration Test to check if your endpoints work as expected when combined with other APIs or services.

Schema Integration Tests

Select a corresponding collection from the list and click Add Integration Test. You will only see available collections in the list.

Add Integration Test to Schema

Adding contract tests

If you're writing tests to ensure your API is working according to its specification, you can use Contract tests. In API > Test, click Add Contract Test.

Contract Test Schema

Select a collection from the list and click Add Contract Test. You will only see available collections in the list.

Add Contract Test to Schema

Observing an API

You can link monitors running on collections in your current workspace to an API. From the API Builder Observe tab, you can create a new monitor, or add an existing monitor.

Schema Monitors

Creating a new monitor

In API > Observe, click Add Monitor and choose Create new monitor.

Create Monitor for Schema

In Select requests to monitor, specify a name and click Generate Collection and Continue.

You can also create a new monitor on an existing collection—select Use an existing collection and choose a collection. Click Select Collection and Continue.

Create Monitor for Schema

Adding an existing monitor

You can add an existing monitor to your API. In API > Observe, click Add Monitor and choose Add existing monitor.

Schema Monitors

Select a monitor from the list and click Add Monitor. You will only available monitors in the list.

Schema with Existing Monitor

To add a monitor to a specific version of your collection, check out how to set up monitors.

Next steps

For more information on building your APIs in Postman, check out the following resources: