Curate your public collection's requests for the Postman API Network

You can curate your collection's requests to communicate your public API's capabilities to your API consumers. A well-curated collection invites your API consumers to fork and use your APIs—and gets them to their first 200 OK response in the fewest steps as possible.

Add requests to your collection

Next to your collection, select View more actions. Then, select Add request.

To learn more, see Add API requests to Postman Collections.

Add the requests that matter the most to your API consumers. For example, if you're adding requests to your API reference collection, add all your public API's endpoints and their HTTP methods. If you're adding requests to your overview collection, add requests to help your API consumers get started and understand your public API's capabilities.

Use the following guidance to add requests:

• Add one request per operation or use case. Don't overwhelm your API consumers with multiple requests for the same operation. Add examples, instead.

• Showcase use cases and workflows. To showcase specific use cases and workflows, add such requests to your overview collection. Such requests show your API consumers how to use your public API in the real world.

Add examples to your requests

Open a request and select Send. Then, in the response pane, select Save Example.

To learn more, see Create examples of request responses to illustrate API use cases.

Add examples that show your API consumers how your API works. For example, if you can create a variety of marketing campaigns with a single operation, add one request. Then, add examples to that request to show how to create such marketing campaigns.

Document your requests

Select the collection's Overview tab and select View complete documentation. To rename a request, select its name and rename it. To write a new description, select the request's description and write a new description. Repeat for each request.

To learn more, see Document your APIs in Postman.

For consistency, use the same guidance for naming your collection and writing a description for it.

Organize your collection with folders

Next to your collection, select View more actions. Then, select Add folder. To add subfolders, next to each folder, you can do the same by selecting View more actions > Add folder.

To learn more, see Add folders to a collection.

Organize your collection to streamline it, make it more scannable, and help your API consumers navigate your API requests. If you're organizing your overview collection, use the following guidance to organize your collection:

• Mirror your onboarding steps. Go back to your collection description and the steps you outlined there and mirror those steps with your folders and subfolders. For example, if you use multiple API requests to set up an account, put those in a folder called "Set up an account".

• Cover the basics, such as authentication and authorization. Ensure you cover the basics, such as authentication and authorization and any API request that gets your API consumers to their first 200 OK response.

• Showcase important use cases and workflows. Create folders to group your API requests by use case and workflow. For example, if you want to showcase your e-Commerce APIs, create "Add to cart" and "Check out" folders.

• Consider adding a support folder. Create a folder that's dedicated to addressing common issues. Such a folder could include examples of typical errors and how to resolve them.

• Research what your users need. Before you finish preparing your collection, review your support channels, forums, and community resources. Identify your API consumers' most common challenges and address them directly in your collection.