Managing Postman Collection items with the Postman API

Ask the Experts and Postman Tips
, ,
1

As you may know, you can use Postman Collections to create groups of saved requests for designing, testing, and documenting your APIs. With the Postman API, you can manage your collections programmatically with the /collections endpoint. But did you know that Postman API also supports programmatically managing your collection’s items?

The Collection Items endpoints provide endpoints that enable you to manage a collection’s requests, responses, and folders. The Items folder, located in the Postman API’s Collections folder, contains the endpoints for managing these items. We’ve also included several examples to help you programmatically build your collections.

Some examples of how you can leverage these endpoints include:

  • Adding responses to existing requests. Use the POST /collections/{collectionId}/responses endpoint to add a response to a collection’s request.
  • Modifying requests and responses for large collections. Performing a PUT on a large collection can be difficult, as large request bodies can result in performance issues or exceed the Postman API’s size limitations. In such cases, you’ll want to only update the requests or responses in your collection. For these situations, use the PUT /collections/{collectionId}/requests/{requestId} and PUT /collections/{collectionId}/responses/{responseId} endpoints. The payloads for these endpoint responses are much smaller than when updating an entire collection.
  • Updating the authentication of all requests in a folder to inherit from the parent. Use the PUT /collections/{collectionId}/requests/{requestId} endpoint to have a request inherit its authentication from the parent collection or collection item. To do this, set the auth, currentHelper, and helperAttributes values as null.
  • Changing a test’s JavaScript code for several requests. You can use the PUT /collections/{collectionId}/requests/{requestId} endpoint to programmatically update a request’s scripts.

For more about collections and understanding the specification behind them, check out our Postman Collection Format documentation.

Next, let’s dive deeper into automatically creating requests and responses for your collections.

Using curl to create requests and responses

curl is a command-line tool for transferring data specified with a URL syntax. It’s a very popular tool for developers that’s used in scripts and in CI/CD environments. Postman can use curl to export requests. You can also import curl commands into Postman as a request.

We’ve created a command-line utility that parses output files coming from curl commands, then uses that data to create collection requests and responses with the Postman API. You can find the code that implements this utility in the save-as-postman-request GitHub repository. It’s a JavaScript code (Node.js) that:

  • Parses the curl output to extract all the request and response information needed, such as status code, headers, and the response body.
  • Calls the Postman API to create the corresponding request and/or response.

Prerequisites

Before getting started with the following examples, make sure to save your Postman API key as a POSTMAN_API_KEY system environment variable.

These examples will use the POST /collections/{collectionId}/requests and POST /collections/{collectionId}/responses endpoints. Both of these endpoints provide examples of GET and POST requests you can reference for more information.

Creating a POST request and response

  1. Save the request body in a REQUEST_BODY environment variable:

    export REQUEST_BODY=$(cat request_body_example.json)

    This is necessary because the curl output doesn’t contain the request body. If it isn’t provided, the request body will be empty in the requests and responses you create.

  2. Run the following curl command. We’ll use this to save a response and all of its outputs to a curl_output.txt file:

    curl -v -X POST --location 'https://postman-echo.com/post' \
--header 'Content-Type: application/json' \
--data $REQUEST_BODY > curl_output.txt 2>&1

    Note that the command uses the verbose (-v) option. This is required, as we need as much information as possible to build the proper requests and responses.

  3. Process the file with the following command. This creates a request in the collection specified in the collectionId argument:

    ./savePostmanRequest.js --inputFile curl_output.txt  --collectionId 12345678-c05fb60e-bb28-4e7b-9cf7-55ada6ab320c --requestName 'Example from command line'

    The command’s response will look like the following:

    Request created with id e057b34d-04b7-543f-c69a-069b48a6617a
Response created with id d2715ac5-b9b9-7e6f-e71d-e21040248939

Creating a GET request and response

  1. Run the following command. We use this to save a response and its output to a curl_output_get.txt file:

    curl -v -X GET --location 'https://postman-echo.com/get?param=value' \
--header 'Content-Type: application/json' > curl_output_get.txt 2>&1

  2. Process the file using the command. This creates a request and response in the collection specified in the collectionId argument:

    ./savePostmanRequest.js --inputFile curl_output_get.txt  --collectionId 12345678-c05fb60e-bb28-4e7b-9cf7-55ada6ab320c --requestName 'Example from command line get' --responseName='Get response'

  3. The command’s response will look like the following:

    Request created with id 40310d86-2c98-f1a5-2b89-37506ed8f489
Response created with id c8d4066a-b736-a001-73fd-ad8d72ed76e9

Adding a new response example to an existing request

You can also add new examples to an existing request by passing the --requestId argument to the command:

./savePostmanRequest.js --inputFile curl_output.txt --collectionId 12345678-c05fb60e-bb28-4e7b-9cf7-55ada6ab320c --responseName='Another post response' --requestId=12345678-536730af-5663-15c7-0625-43c0d5b89030

The command’s response will include only the newly-created response’s ID:

Response created with id 973b0ed3-9d3d-9d72-8e1e-6b57d1524e1b

You can find more information about this command in the save-as-postman-request repo.

Your work with the Postman API

These are just a few examples of how you can automatically create requests and responses with the Postman API. Do you have a specific use case? How would you use the Postman API in your development process to keep your code in sync with your workspaces and collections? Comment below and tell us about your own use cases!

7 Likes