The Good Collection

Joyce

March 8, 2018

Postman Collections are a tidy way to group your requests together so you can save, reuse, and share them with others. More than that, they are the cornerstone for more advanced features in Postman.

What makes a Postman Collection good? A good collection clearly describes the behavior and usage of your API. Most collections can be lumped into one of these buckets.

These 2 types of collections typically have a different audience, are written by different authors, and will contain different content. For these reasons, it’s a good practice to maintain separate collections for testing and documentation.

Related: Postman Collection best practices

Collections for testing

The first type of collection is for testing the behavior of your API. You might be communicating with other team members about how your API functions or demonstrating the API’s behavior under various circumstances.

Here’s some tips for writing collections for testing:

Scripts

Take advantage of the pre-request and test script tabs to write JavaScript code. There’s handy snippets to get you started. For example, write a Postman tests to make assertions about the correctness of your API. For example, check the response status codes or response body data type.

Branching and looping

Mimic your workflow by using postman.setNextRequest() to control the order of requests that would normally run sequentially within a collection. If a response was successful, then Request B should be called next. If a response was not successful, then on to Request C!

Logs

Log helpful error messages. New users can then view these errors in the Postman console. For example, let them know if certain required variables are missing.

Collections for documentation

The second type of collection is for documentation, or showing others how to consume your API. Documentation should cover why the APIs used are important, the how and why to use each endpoint, and examples aplenty. In a Postman collection, there are several places to explain to the user what’s going on.

Here’s some tips for writing collections for documentation:

Examples

Demonstrate concrete examples of requests and responses so the user clearly knows what to expect and can troubleshoot their own requests more quickly.  Descriptions

Descriptions can be added for each request, folder and collection to explain the particulars of an endpoint – what it is, when to use it, and why you would want to use it. Style your descriptions and embed screenshots using markdown to help people who are skimming through the documentation. You can also add parameter descriptions in the various data editors within the Postman app.

Publish documentation

Understanding what’s going on while you’re working in the Postman app is great, but sharing web-viewable documentation using Postman can be an easier way to show someone else how to use your technology.

Tips for communicating clearly with a good collection

No matter if your collections are for testing or documentation, collections are a way for humans to collaborate. As such, collections should be human readable. This might benefit those who are using your API, your teammates working on the API, or even your future self.

1. 1. Stay clean and tidy: While the collection is the top-level of organization, you have folders that can group together related requests or demonstrate a specific workflow. Secondary folders can then be nested under primary folders, and so on.
      
   2. Include a quickstart: Help a sister out and include a quickstart somewhere in the collection. If I’ve never used your API, get me up and running quickly, and I’ll be more likely to explore the rest of your API, or at least I’ll be more optimistic about it. If you have a number of required variables, consider including a table (written in markdown) that breaks it down for the user
      
   3. Explain authorization: Most APIs require some sort of authorization. Even though Postman has authorization helpers that abstract some of the repetition and tedium, you will want to be explicit about the process so developers can easily roll it into their own apps if they need to.
      
   4. Stay up to date: If you’re publishing documentation using Postman, any changes made to your collection will automatically be synced and keep your web documentation up to date. Now, you just have to keep your Postman Collection up to date.
      • If you’re sharing a collection with your teammates on a Postman Pro or Postman Enterprise team, your updates are all synced in real time.
        
      • If you’re sharing your collection with the Run in Postman button or a collection link, it’s a reflection of your collection at the time you shared it. After you make any changes, you will want to refresh the collection to be shared. Of course, this won’t update the collection on their local machine, but will allow them to import the latest version.

Want to check out some examples of good Postman Collections? Swing by the Postman API Network to see who is running in Postman. These publishers have collections ready to import into Postman so you can easily get started with their APIs. If you’re an API publisher, come join the network!