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
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.
Click New, then select API or click +.
You must be signed in to your Postman account to take this action.
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 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.
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 YAML as the default language. To use a different schema type or language, choose it from the drop-down list.
The left pane of the schema editor displays an outline of your schema. When you first open the editor, the top level of nodes will be expanded, and the rest of them collapsed. Click nodes to expand or collapse them. Click an element in the outline to jump to it in the editor. You can also click the outline button to hide or show the outline.
In the schema editor, when you hover over a '#ref' component and press the Command key, a popover displays the first 200 characters of the reference component. When you Command-click the reference component, it will jump to the reference location.
In the upper right of the schema editor are 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 a Generate Collection option on the right-hand side of the tabs:
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 a 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.
Click the bell icon on the top right corner to view the notification. The popup will indicate further information about the change that was made to the API.
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 View schema changelog to access the full changelog or View API to view the API in Postman.
You will not receive notifications for changes made by yourself.
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
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 Postman.
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
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: