Developing an API

In the Postman API Builder, you can develop your API by linking it to documentation, environments, and mock servers.

When you add documentation, tests, mocks, monitors, and environments, only the elements in the current workspace will be listed in the selection dropdown list.

Adding documentation

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

Creating new documentation

To create a new collection and generate an API's documentation from your schema:

  1. In the API version Overview tab, next to Documentation, select + and choose Create new documentation.

  2. Specify a name, configure how the collection should be generated by selecting Show advanced settings, and select Create Documentation.

Adding existing documentation

  1. In the API version Overview tab, next to Documentation, select + and choose Add existing documentation.

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

Viewing documentation

You can view the documentation for your API from within API Builder. Select any of the documentation listed under the Documentation heading to open it in a new window.

You can also view the documentation in the Documentation tab. In the upper left of the tab is a dropdown list where you can choose which collection is shown, and add or generate another documentation collection.

Select View Collection from the Documentation tab to see the documentation's collection.

Adding an environment

You can link specific environments in your workspaces to specific versions of an API.

  1. In the API version Overview tab, next to Environments, select +.

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

Adding a mock server

You can link mock servers for a collection to an API, by creating a new mock server, or adding an existing one.

Creating a new mock server

  1. In the API version Overview tab, next to Mock Servers, select + and choose Create new mock server.
  2. Select a collection and configure the mock server as outlined in

Creating a mock from an API.

Adding an existing mock server

  1. In the API version Overview tab, next to Mock Servers, select + and choose Add existing mock server.

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

Removing elements from an API

You can remove an associated documentation collection, environment, or mock server collection from an API.

In the API version Overview tab, hover over the element and select Remove icon to the right of it.

This will only remove the association between the element and the API version. It will not delete the element or remove it from your workspace.