One of the ways developers have to interact with the Box Platform API is our publicly available Postman collection.

This is fundamental for Box, since it constitutes one of the main tools developers use, either for exploring the API or testing their integrations.

Previously Box automated the collection deployment based on changes in the public API. This time we decided to take it to the next level.

Before we get to the details, let’s look at how we had our deployments set up.

When our engineering updates the Box API, an event is dispatched to our Postman collection repo.

This in turn triggers the collection deployment to the public Postman workspace, updating the collection in bulk, not just the changes.

This had some disadvantages:

• Sometimes we get a HTTP 500 server error, that crashes the deployment and leaves our public collections empty.
• Always updating the entire collection takes time, around 7 minutes each collection. We have an English and Japanese version.
• Pulling changes from the public collection, also takes a few minutes, possibly leaving developers on edge and creating friction on keeping their fork up to date.
• The Box API is fairly mature, we rarely have the need to re-deploy the entire collection. We may add a couple of methods, but the bulk are documentation updates, parameters, etc. It doesn’t seem right to update the entire collection for these changes.

The first thing we did was to change the way we deploy the collection:

Deploying first to a private workspace and then use the collection merge from the Postman API, immediately eliminated the empty collection issue.

Now our developers, especially from Japan, won’t find or pull changes from an empty collection anymore.

Next we were missing some sort of incremental deployment to update only what has changed.

Incremental deployments

The Postman API provides us with methods to manipulat