Prepare your public workspaces for the Public API Network

Before making your APIs available on the Postman Public API Network, Postman recommends following these best practices and tips to help API consumers begin using your APIs.

Customizing your team profile

Customize your team profile with important information about your team. Add information that identifies you as the real company on the Public API Network. By default, your profile is only visible to your Postman team. Make your team profile public to make your profile show up on Postman's Explore page.

Organizing public workspaces

You can organize the requests in your public workspace using collections and folders to help consumers begin interacting with your APIs. Collections enable you to group saved requests, and folders enable you to organize requests into folders by category, such as domain, service, and use case.

A workspace is a group of schemas, collections, variables, tests, and more that describe how to interact with your APIs. Typically, developers begin with collections when learning how to interact with APIs. Keeping your requests organized in collections and folders will help guide consumers towards requests relevant to their interests.

Creating API examples for different use cases

You can create collections with specific example use cases to help consumers fork your collections and begin interacting with your APIs. Example use cases can include integrations, automation, authentication and authorization, and more.

Creating environments for different use cases

You can create environments for different use cases, such as testing and production, and add them to your public workspace. This helps consumers understand what they need to configure with your API for their use case.

Protecting sensitive data

When creating and sharing environment variables, specify example values as the Initial value for the variable. Don't add sensitive data as the Initial value because it's shared with users who can access the environment. The Current value is used in your local instance of Postman, and is never synced to your account or shared with your team unless you choose to persist it.

Writing detailed documentation

Write detailed documentation for each collection and request to help consumers learn how to consume your APIs. The following best practices will help you write clear and concise documentation:

• Standardize the language in your workspace and its APIs.

• Use meaningful names for requests, collections, and folders. Use names that developers would expect.

• Reuse variables throughout your collection. Use variable names that are meaningful and set a clear expectation for their related values.

To learn more about writing detailed documentation, see The Good Documentation Checklist.

Defining and describing variables

For your variables, you can write documentation describing the expected value and provide example values. Variables can be defined independently or stored within environments, and then applied across collections, enabling you to use variables for authentication, pagination, and other aspects of working with APIs. Variables can also define a state across multiple APIs and collections.

Writing descriptions for folders and requests

At either the collection or folder level, Postman recommends writing detailed descriptions that explain how to sign up for and get started with your API. You can use keywords in your descriptions to increase your API's discovery in organic search results and Postman search results.

To learn more about collections and folders, see Using collections.

Adding examples to requests

Save examples of your API's requests, responses, and messages to use examples in your documentation. This enables consumers to test your API using example data.

Adding authorization details

You can create documentation explaining how to authorize with your API. You can mention this in the workspace description or documentation description if you have several API request workflows or a more complicated authorization schema. To learn more, see Including authorization details.

You can also set up API authentication for your API. This enables Postman to automatically recognize a request to your API that requires authentication, and prompt your API's consumers with steps to set it up.