- Installing and updating
- Navigating Postman
- Sending your first request
- Managing your account
- Syncing your work
- Discovering templates
- Creating your first collection
- Creating a workspace
- Setting up your Postman app
- Importing and exporting data
- Troubleshooting app issues
- Building requests
- Authorizing requests
- Receiving responses
- Grouping requests in collections
- Using variables
- Managing environments
- Visualizing responses
- Specifying examples
- Using cookies
- Working with certificates
- Generating client code
- Troubleshooting requests
- Scripting in Postman
- Writing pre-request scripts
- Writing tests
- Using the Collection Runner
- Scheduling runs with monitors
- Building request workflows
- Importing data files
- Working with your team
- Defining roles
- Requesting access
- Sharing your work
- Your Private API Network
- Commenting on collections
- Versioning APIs
- Using version control
- Using the API Builder
- Managing and sharing APIs
- Validating APIs
- Monitoring APIs
- Setting up a monitor
- Viewing monitor results
- Monitoring APIs and websites
- Set up integrations to receive alerts
- Running Postman monitors using static IPs
- Troubleshooting monitors
- Monitoring FAQs
- Analyzing with reports
- Documenting your API
- Authoring your docs
- Publishing your docs
- Viewing documentation
- Using custom domains
- Publishing templates
- Publishing to the API Network
- Submission guidelines
- Managing your team
- Purchasing Postman
- Configuring team settings
- Utilizing audit logs
- Onboarding checklist
- Intro to SSO
- Configuring SSO for a team
- Logging in to an SSO team
- Microsoft AD FS
- Custom SAML in Azure AD
- Custom SAML in Duo
- Custom SAML in GSuite
- Custom SAML in Okta
- Custom SAML in Onelogin
- Custom SAML in Ping Identity
- Migrating to the current version of Postman
- Developing with Postman utilities
- Postman API
- Echo API
- Collection SDK
- Postman Runtime library
- Code generator library
- Postman Collection conversion
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
- Watching an API
- Testing an API
- Observing 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.
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.
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.
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.
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.
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 an environment
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.
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
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 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.
You can link the documentation generated from your collections to specific versions of an API.
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.
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 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.
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.
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.
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.
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.
Specify a name for the collection, configure how the collection should be generated by clicking Show advanced settings, then click Generate Collection and Continue.
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.
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.
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.
For more information on building your APIs in Postman, check out the following resources: