Examples show your API endpoints in action and give more details on how requests and responses work. You can add an example to a request by saving a response, or you can create an example with a custom response to illustrate a specific use case. Once you've created examples, you can use them to set up a mock server or add more detail to your API documentation.
In Postman, an example is a pairing made up of a
request
and a related
response
. Each example includes a request part (method, URL, parameters, headers, and body) and a response part (status code, body, and headers). You create examples by adding them to requests in collections, and one request can have multiple examples.
Having multiple examples for one request is useful for illustrating the different ways an endpoint can respond to a request. You might have examples that respond with different status codes (such as 200 or 404) or that return different data (or no data at all).
Examples are useful in several ways. Developers and testers can refer to examples to better understand how an endpoint functions in different scenarios. Examples can also be used to
set up mock servers
, so developers and testers can start
writing code
against your API—even before it's complete. In addition, you can include examples in your API's
public documentation
to help anyone in the world who uses your API.
An example is always associated with a
request
in a
collection
, and a request can have more than one example. To add an example to a request, send the request and then save the response as an example. You can also manually add an example to a request and define a custom response. After adding an example using either method, you can edit it at any time to make changes.
For optimal Postman performance, example responses must be smaller than 5 MB.
When saving a
response
in Postman, you have the option to save it as an example.
Select
Collections
in the sidebar.
Open a request and select
Send
.
In the response pane, select
Save as Example
for HTTP, GraphQL, and gRPC responses, or
Save Response
for WebSocket, Socket.IO, and MQTT responses.
For
gRPC examples
with streaming methods, you must end the stream before saving the response/message stream as an example.
With a custom example, you can define how both the
request
and the
response
look, including the status code and response body.
Select
Collections
in the sidebar.
Select the more actions icon
next to a request and then select
Add example
.
Enter a name for the example.
Edit the request part of the example.
Add any parameters or headers as needed.
Enter the request body and select a content type.
Edit the response part of the example.
Enter a
Status Code
(such as
200
or
404
).
Enter the response body and select a content type.
Add any headers as needed.
Select
Save
to save the example.
Examples are stored in a collection with their associated requests. You can try an example by opening the example as a request in a new tab.
Select
Collections
in the sidebar.
Select a request, and then select an example to open it.
Select
Try
to open the example as a request in a new tab. The request will automatically send in the new tab.
Review the request and response details.
The new request isn't automatically saved.
The name of the example you're trying is next to the request's name in the workbench. Select the example's name to open it in a separate tab.
Optionally, you can select
Save
to save the new request to a new or existing collection in your workspace.
Choose a location to save the new request, and then select
Save
.
You can edit an example at any time to remove sensitive tokens, change the status code, or make any other adjustments.
To edit an example, do the following:
Select
Collections
in the sidebar.
Select a request, and then select an example to open it.
Make any changes to the example request or response.
Select
Save
to save the example.
To edit an example after trying it, do the following:
Select
Collections
in the sidebar.
Select a request, and then select an example to open it.
Select
Try
to open the example as a request in a new tab.
Make any changes to the new request.
Select
Send
.
In the response pane, select the more actions icon
and then select
Update example
. You will receive confirmation once the example is updated.
The new request isn't automatically saved.
Optionally, you can select
Save
to save the new request to a new or existing collection in your workspace.
Choose a location to save the new request, and then select
Save
.
You can share examples with collaborators by going to the example you want to share in the sidebar. Select the more actions icon
next to the example you want to share, then select
Share
.
For more details about sharing examples, see
Share your work in Postman
.
Select the comments icon
in the right sidebar and enter your comment.
(Optional) Select the
Watch collection
checkbox to be notified when there are changes to the collection that the example is in.
Select
Comment
to add your comment.
You can learn more about
using comments to collaborate on examples
.
Duplicate an example to add a new example using an existing example as a base. You can then edit the copied example to change the name, status code, or any other part of the request or response.
Select
Collections
in the sidebar.
Select the more actions icon
next to an example, and then select
Duplicate
.
Make any changes to the example request or response.
Select
Save
to save the example.
Deleting an example removes it from the collection and from the associated API documentation. Any mock servers you have set up can no longer use the example to return a response.
Select
Collections
in the sidebar.
Select the more actions icon
next to an example, and then select
Delete
.
Select
Delete
to confirm.
Postman automatically
generates documentation
for every collection you create. The generated documentation
includes any examples
that have been added to the collection. If you edit an example, the documentation is automatically updated with your changes.
Examples give more details and clarification for your API and help your team to work together on API development. Front-end developers, back-end developers, and testers can all work in parallel, using the examples in the documentation for guidance or to set up
mock servers
.
You can
publish your documentation
to make your examples publicly available to anyone in the world.
