> This page is for Postman Docs, version Latest (v12) (default). > For other versions, use one of these documentation indexes: > - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt > - v11: https://learning.postman.com/v11/llms.txt > For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Curate your public collections for the Postman API Network Curate your public collections to introduce your public APIs, communicate their capabilities, and create a great developer experience. A well-curated collection invites your API consumers to [fork](/docs/collaborating-in-postman/using-version-control/forking-elements/) and use your APIs, and gets them to their first 200 OK response in the fewest steps possible. > **Important** > > Protect your sensitive data. If Postman detects any API keys, tokens, or similar, it replaces them with placeholders. To learn more, see [Postman Secret Scanner](/docs/administration/managing-your-team/secret-scanner/overview/). ## Name your collection Name your collection something that communicates its purpose. For example, name your [API reference collection](/docs/postman-api-network/showcase/prepare/public-collections/#create-your-public-api-reference-collection) so it's clear it's the API reference for the public APIs in your workspace. Name your [overview collection](/docs/postman-api-network/showcase/prepare/public-collections/#create-your-public-overview-collection) so it's clear it's the starting point for those APIs. Use the following guidance to choose a name: * **Use keywords that speak to your target audience.** Choose words and phrases that your API consumers may search for, such as those that relate to what your API does, specific use cases, and common industry terms. For example, instead of "Data API", name your collection "Financial Market Data API" or "Get started with the Financial Market Data API". * **Choose a descriptive yet concise name.** Convey what your API does in the fewest words possible. Use action-oriented language and avoid vague terms. For example, instead of "User API", name your collection "Create customer accounts API". * **Be consistent across your workspace and collections.** Consistency improves your API consumer's ability to scan and navigate your workspace and collections. For example, if you name a collection "Financial Market Data API", name a similar collection "Financial Market News API" (and not "APIs for finance news"). > **Info** > > **Tip:** Use 🤩 emojis to make your collection name stand out. To learn more about renaming a collection, see [Configure a collection](/docs/use/use-collections/create-collections/#configure-a-collection). ## Write a description for your collection Write a description that gets your API consumers to their first API request and 200 OK response in the fewest steps possible. Use the following guidance to write a description: * **Introduce your APIs and the services they offer.** Give your API consumers an overview of your APIs. You can add screenshots, videos, and links. List your APIs, highlight their value, explain what each does, and define any key concepts your API consumers need to understand. Help your users navigate your collection with a table of contents that links to folders and requests within your collection. * **Get your API consumers started.** Focus on the steps each API consumer must complete to get their first 200 OK response, and document these steps for them. For example, if they must sign up for an account, give them a link to where they can sign up. If you host "Get started" documentation elsewhere, link to it. * **Explain authentication and authorization.** Often, authentication and authorization introduce the most friction between your API consumers and your APIs. Outline the steps someone must complete to make their first successful API call. * **Link to further documentation, such as tutorials.** If you have integration guides and tutorials, link to them to let your users know what to do once they get their first 200 OK response. * **Link to help and the community.** Add links to your support channels, forums, and community resources. This ensures your API consumers know where to go when something goes wrong. To learn more about editing a collection's description, see [Configure a collection](/docs/use/use-collections/create-collections/#configure-a-collection). ## Add requests to your collection Add the requests that matter the most to your API consumers. For example, add all your public API's endpoints and their HTTP methods to your API reference collection. Add requests to your overview collection that 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](#add-examples-to-your-requests), 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. > **Info** > > Your API consumers will be able to get to their first 200 OK using the **Start here** wizard in the request **Overview** tab. The content for this wizard is autogenerated. To get it customized, go to the [Postman Support Center](https://www.postman.com/support/) and click **Submit a request**. To learn about the consumer side of this onboarding experience, see [Use public elements](/docs/postman-api-network/explore/consume/#use-public-elements). To learn more, see [Add API requests to Postman Collections](/docs/use/use-collections/add-requests-to-collections/). ## Add examples to your requests 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. To learn more, see [Create examples of request responses to illustrate API use cases](/docs/use/send-requests/response-data/examples/). ## Document your requests Give each request a name and description, using the same guidance you used to [name your collection](#name-your-collection) and [write a description for it](#write-a-description-for-your-collection). Keep each request's description short, so your API consumers can see the request onboarding wizard. To learn more, see [Document your APIs in Postman](/docs/publishing-your-api/api-documentation-overview/). ## Organize your collection with folders Organize your collection with folders and subfolders 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: * **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. To learn more, see [Add folders to a collection](/docs/use/use-collections/manage-collections/#add-folders-to-a-collection). ## Set up authentication Postman recommends you set up Guided Auth with OAuth 2.0 for your domain. When an API consumer uses an endpoint on your domain, Postman prompts them to authenticate through Guided Auth. This is the fastest way to authenticate and creates the best developer experience. If you're not ready to set up Guided Auth, set up authorization for your collection instead. All requests in the collection inherit it. When your API consumers fork your collection, they complete the remaining details. To learn more, see [Set up Guided Auth for public APIs in Postman](/docs/publishing-your-api/setting-up-authentication-for-public-apis/) and [Add API authorization details to requests in Postman](/docs/use/send-requests/authorization/specifying-authorization-details/). ## Use collection and environment variables Use variables for values your API consumers need to change, such as an API key, so they can update the value in one place. You can use collection variables, or create environments for different contexts. For example, create one environment for your sandbox and one for production, each with its own API key value. > **Note** > > API consumers can't fork your global variables. Don't use them in your public workspace. Use collection and environment variables instead. Pin your environments to your collection. When an API consumer forks a collection that has pinned environments, they also fork the pinned environments by default. If you set a default pinned environment, Postman makes it the active environment in their forked collection. To learn more, see [Reuse data with variables and environments in Postman](/docs/use/send-requests/variables/variables-intro/) and [Pin environments to collections](/docs/use/send-requests/variables/pinned-environments/). ## Add scripts Use pre-request and post-response scripts to automate tasks and give your API consumers immediate feedback, such as how to address errors. For example, you can write a script that formats dates to the API's expected format. If your API uses access tokens, you can write a script that takes the token from a response and uses it in later requests. To learn more, see [Use scripts to add logic and tests to Postman requests](/docs/tests-and-scripts/write-scripts/intro-to-scripts/).