Using the API Builder

You can design your API directly in Postman using the API Builder. By defining your schema in APIs on the left of Postman, 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.

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.

• Creating an API

• Defining an API

  • Editing your schema
  • Generating a collection
• Watching an API

• Developing an API

  • Adding a mock server
  • Adding documentation
  • Adding an environment
• Testing an API
• Observing an API

Creating an API

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

If it is your first time using the API Builder, you can take a tour of its features by clicking Start from the API tab or from the Create new API modal.

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

Enter a name and a version, then select a schema type and format for your API. You can optionally import an API specification directly at this stage—if you don't, Postman will populate your API with a sample specification you can edit at any time.

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.

You can rename, delete, or remove the API 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.

You can create APIs from your workspaces dashboard in the 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 using its specification. You can also generate a collection from a spec.

• Editing your schema
• Generating a collection

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

Editing your schema

The Define tab in your API will include a specification (either one you imported or a sample Postman added when you created the API).

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.

Postman will indicate validation errors as you work on your schema.

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:

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

You can also configure how the collection should be generated by clicking Show advanced settings.

Watching an API

The watch option allows you to receive an email/in-app notification when your team member belonging to the same workspace modifies the API for example updating the schema, attaching an element to the API, adding a comment to the API and so on.

Once you've created the API, click the watch option to start watching the API.

After enabling the watch option, you will get a pop-up notification stating "You are watching this API."

Being a watcher, you will be notified whenever the API schema is modified. If you're watching an API in your current team workspace, you will see notifications whenever changes are made to the schema in Postman even if you are logged into a different account.

Click the bell icon on the top right corner to view the notification. The popup will indicate further information about the updated schema.

In addition to this, you will receive an email with the information regarding who has made the change, what the change was, and when it was made.

Click the View Schema button to view the API in the web dashboard.

If you created the API and modified the schema from the same account, you will not receive email or in-app notifications for changes made.

Developing an API

Once you have a schema in the Postman API Builder, you can develop your API using version tagging, and link it 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

  • Creating a new mock server
  • Adding an existing mock server
  • Editing a mock server

• Adding documentation

  • Creating new documentation
  • Adding existing documentation
• Adding an environment

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.

Creating a new mock server

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

You can base your mock server on different collections:

• Generate collection from schema: To create a mock server based on a collection generated from your schema, enter a name, configure how the collection should be generated by clicking Show advanced settings, and click Generate Collection and Continue
• Use an existing collection: Select a collection from the drop-down list and click Select Collection and Continue
• Create a new collection: To start a new collection for your mock server, enter the requests your collection will contain, and click Create Collection and Continue

Adding an existing mock server

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

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.

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.

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

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.

Creating new documentation

In the API > Develop tab, click Add Documentation > Create new documentation.

Specify a name, configure how the collection should be generated by clicking Show advanced settings, and click Generate Collection and Continue.

Adding existing documentation

In the API > Develop tab, click Add Documentation > Add Existing documentation.

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.

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

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
• Adding integration tests
• Adding contract tests

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.

You can add a new or existing test suite:

• Create new test suite: Enter a name, configure how the collection should be generated by clicking Show advanced settings, and click Generate Test Suite.
• Add existing test suite: Choose an available collection from the list and click Add Test Suite. You will only see available collections in the list.

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.

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

You can add a new or existing integration test:

• Create new integration test: Enter a name, configure how the collection should be generated by clicking Show advanced settings, and click Generate Integration Test.
• Add existing integration test: Choose an available collection from the list and click Add Integration Test. You will only see available collections in the list.

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.

You can add a new or existing contract test:

• Create new contract test: Enter a name, configure how the collection should be generated by clicking Show advanced settings, and click Generate Contract Test.
• Add existing contract test: Choose an available collection from the list and click Add Contract Test. You will only see available collections in the list.

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.

Creating a new monitor

In API > Observe, click Add Monitor and choose Create new monitor. You can choose between generating a collection from a schema, using an existing collection, or creating a new collection.

Generating a collection from a schema

Specify a name for the collection, configure how the collection should be generated by clicking Show advanced settings, then click Generate Collection and Continue.

Using an existing collection

To create a new monitor on an existing collection, select Use an existing collection and choose a collection in the dropdown. Click Select Collection and Continue.

Creating a new collection

To create a new collection to monitor, choose Create new collection. Add the requests you plan to monitor, specifying the method and URL, as well as the status code and response time you want to check. Click Create Collection and Continue.

Adding an existing monitor

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

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

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:

• Versioning APIs
• Managing and sharing APIs
• Viewing and analyzing APIs
• Validating schema and elements