Template guidelines

Adding your profile and docs to the Postman Templates can expose your collections to the Postman community, helping them to onboard with an API and to learn from your example requests. To get the best out of your template listing, follow a few tips that will aid discovery of your documentation, and make your collection templates as usable as possible.

Templates Homepage

Check your collection in the app

Your documentation represents a Postman collection, with both the textual information content—and the executable requests bundled via the Run in Postman button—pulled from your collection setup in Postman. For this reason, it's worth walking through the process of importing the collection yourself, checking the information that appears inside the Postman app as well as in the docs (for example descriptions on the collection, requests, and parameters).

If your collection contains lots of requests, consider grouping them into folders to make the documentation and imported templates easier to navigate.

Check your docs on the web

When you publish documentation for a Postman collection, you will author the content inside the Postman app in Markdown, but consumers will view it in the web browser as HTML. For this reason, it's essential to read through your docs in the browser to get a feel for how they will walk developers through the process of using your API, and to ensure your collection information is rendering as expected (this is particularly important if you're using variables to populate some of the content).

Tailor your examples

The sample code section in your docs will play a significant role in how effectively developers are able to onboard with your API or use your template requests. Your collection examples will automatically populate in the docs code, so it's worth taking the time to ensure that the examples contain readable, prototypical usage of your API endpoints.

Add contextual material

When developers attempt to learn how to interact with an API, they need to understand more than just what each endpoint receives and returns. By introducing your template with contextual material explaining the purpose of the collection at a high level, and outlining how the different requests fit together (if relevant), you will help new users get off to a more effective start. Ideally include quickstart information that lets developers make a request as soon as possible.

If your template requires authentication, make sure you include instructions explaining what developers need to do to acquire and use credentials. Other top level info that applies across endpoints can appear in your collection description so that it renders at the top of your documentation page.

Complete your profile

When you publish to the Postman templates, potential users can see your profile if they search via the web. Taking the time to fill out your profile gives you a chance to introduce yourself to the people considering using your templates. You can include your name, description, a photo, and customize your URL.

Complete your template listing

Your template listing should provide the information developers need to know in order to decide whether they want to try the collection out or not. Try to choose a descriptive name that conveys the purpose of your template without users having to click it to find out more detail. In your description, try to include an overview of what the collection does, with enough detail for people to figure out whether it's of interest to them. You can include a name, summary, description, and categories that will determine how your template is listed when users browse in the app or on the web.

Sample template listings

There are lots of inspiring templates already published that you can learn from. Check out the following notable examples: