Skip to content
Postman API Testing Tips

How To Use Postman Collections

API Testing Blog

What are Postman Collections?

Postman Collections are a powerful feature that allows you to organize and manage your API requests in a structured way. Think of them as folders for your API requests, allowing you to group related requests together and streamline your testing process. Collections make it easier to:

  • Organize your API tests: Group requests by functionality, environment, or any other logical criteria.
  • Share tests with others: Easily share entire collections with other developers or testers.
  • Run tests automatically: Collections can be automated with built-in tools like Newman, enabling continuous integration and continuous delivery (CI/CD) workflows.
  • Document your API: Collections can be used to document your API by adding descriptions, examples, and other relevant information to each request.

Creating a Postman Collection

Let’s start by creating a simple collection for a hypothetical API that handles customer data:

  1. Open Postman: Launch the Postman app or visit the website https://www.postman.com/.
  2. Create a New Collection: Click on the “New” button, then select “Collection”.
  3. Name your Collection: Give your collection a meaningful name, such as “Customer API”.
  4. Add Requests to the Collection: Click on the “Add Request” button to create your first request.

Creating a Request for GET /customers

Here’s a step-by-step guide to creating a request within your collection:

  1. Enter the Request Details:
    • Name: Give your request a descriptive name, such as “Get All Customers”.
    • HTTP Method: Select “GET” since you want to retrieve data.
    • URL: Enter the API endpoint URL, e.g., https://api.example.com/customers.
  2. Add Headers (Optional):
    • If your API requires any specific headers, add them here. For example, an “Authorization” header if you need authentication.
  3. Send the Request: Click on the “Send” button to execute your request.

Adding Variables and Environments

Postman variables and environments contribute to efficient and flexible testing. Let’s explore how to incorporate them:

Setting up an Environment

  1. Create an Environment: Click on the “Environments” button (gear icon) and then “Add”.
  2. Name your Environment: Give it a relevant name like “Development” or “Production”.
  3. Add Variables: Define variables with their corresponding values. For example:
    • base_url: https://api.example.com (Use this variable in your requests instead of hardcoding the full URL).
    • api_key: your_actual_api_key (Replace this with your actual API key).

Using Variables in Requests

  1. Modify the Request URL: Change the URL field to {{base_url}}/customers. This dynamically uses the base_url variable from your environment.
  2. Add Dynamic Headers (Optional): You can use variables in your headers as well. For example, you could add a Authorization header with a value of Bearer {{api_key}}.

By using variables, your requests become more adaptable and reusable. You can switch between different environments (like development, staging, or production) simply by selecting them in Postman.

Organizing Requests with Folders

As your API tests grow, you can organize them into folders for better structure:

  1. Create a Folder: Right-click on your collection and select “Add Folder”.
  2. Name the Folder: Give the folder a descriptive name, such as “Customers”.
  3. Move Requests: Drag and drop the Get All Customers request into the “Customers” folder.

You can create more folders as needed, allowing you to categorize your requests by resource type (e.g., “Orders”, “Products”) or functionality (e.g., “Read Operations”, “Write Operations”).

Running Collections with Newman

Postman Collections aren’t just for manual testing; they can be used for automated testing with Newman.

  1. Install Newman: Newman is a command-line tool for running Postman Collections. Install it using Node Package Manager (npm): npm install -g newman

  2. Export the Collection: Go to your collection in Postman, click on the “Share” button, and then select “Export”. Choose a file format like “Collection v2”.

  3. Create a Newman Command: Open your command line or terminal and use the following command:

    Terminal window
    newman run collection.json -e environment.json
    • Replace collection.json with the name of your exported collection file.
    • Replace environment.json with the name of the environment file (similarly exported from Postman).

Newman will execute your entire collection, reporting on the results of each request. You can configure Newman to run your tests regularly as part of your CI/CD pipeline.

Using Test Scripts for Assertions

Postman’s built-in scripting functionality lets you write code to verify the responses from your API. Here’s how to add test scripts to your requests:

  1. Open the “Tests” tab: Select the “Tests” tab in a request.

  2. Add Assertions: Write code using JavaScript to assert various aspects of the response. For example:

    pm.test("Status code is 200", function () {
        pm.response.to.have.status(200);
    });
    

    pm.test("Response body has customer name", function () {
        pm.expect(pm.response.json().name).to.be.a('string');
    });

This script checks the response status code and verifies that the customer’s name is present in the response body.

Using Postman Collections for API Documentation

Postman Collections can double as a valuable way to document your API.

  1. Add Descriptions: Use the description field for each request and collection to provide information about:
    • Request Parameters: Explain the expected input values.
    • Response Structure: Provide examples of the response JSON format.
    • Error Handling: Explain potential errors and their corresponding status codes.
  2. Include Example Responses: Use the “Examples” tab to add sample responses for different scenarios. This helps visualize the request and response interaction.

By combining descriptions, examples, and tests, your Postman Collections can serve as living documentation that remains synchronized with your API.

Conclusion

Postman Collections are a valuable tool for every developer and tester. They provide a highly efficient way to manage and automate API testing workflows, while also serving as a central repository for API documentation. By mastering the art of utilizing Postman Collections, you can streamline your API integration efforts and ensure reliable, quality APIs.

API Testing Blog