The Postman API provides several endpoints that enable you to programmatically manage your Postman Collections so you don’t have to do it manually with the Postman Desktop or Web app. They include a PUT and PATCH operation, along with a set of collection items APIs used to manage a collection’s requests, folders, and responses (examples).
While the PUT endpoint works well for most collections, it can be slow if you’ve got a collection that’s several megabytes. That’s because the endpoint is synchronous: you have to wait until the collection update finishes before you’ll get a response. Large collections mean longer wait times.
In a previous post, we provided some alternative methods to help you manage large collections. However, these methods are a bit complex, and can potentially complicate the process of updating large collections.
Introducing the respond-async header
To help solve this problem, we’ve updated the PUT to accept a Prefer: respond-async header. You can now update the entire contents of your collections asynchronously!
How it works
When the Postman API receives this header and accepts the operation, the PUT operation is scheduled to complete in a background process. The endpoint returns an HTTP 202 Accepted response that looks similar to the following:
{
"task": {
"id": "be15d43c-XXXX-XXXX-XXXX-1c4228f32f8d",
"status": "in-progress"
}
}
A background task is scheduled to perform the PUT. Along with this header, we’ve added a new GET /collection-updates-tasks/{taskId} endpoint so you can pass the task’s ID and get the status of the collection update. Its response will look something like this:
{
"id": "66ae9950-XXXX-XXXX-XXXX-1e0e47e771af",
"status": "successful"
}
The response’s status field returns three possible values: successful, failed, or in-progress. You can poll the endpoint every few seconds until the process succeeds or fails. Note that the endpoint still has a limit of 100 MB in the request body.
Summary
- You can now update (PUT) a collection asynchronously with the Postman API.
- This is useful for large collections (up to 100 MB) and CI/CD processes that require a fire-and-forget process.