Taking Postman collection deployments to the next level
In this article we'll explore how Box implemented incremental collection deployments using the Postman API's.
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.
Automatic deployments setup
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 manipulate the collection, folders, requests and responses (aka examples). These constitute the bulk of objects types in our collection, but we also need to, once in a while, update the authentication, pre-request scripts, and variables.
We also found some limitations in its usage, these are the rules, we must work with what we have:
- Collection
PATCHis only available for updating the name and description. - Collection
PUTupdates all items, forcing us to update the entire collection.
This means that if we are trying to update any top level collection objects we must update the entire collection. These include:
- Authentication.
- Pre-request script.
- Tests.
- Variables.
- First level object sorting, in our case these are all folders.
Like I mentioned before we don't update these often.
How to detect changes in the objects
This was the key solution to the problem. I needed to find a way of detecting changes in all collection objects.
Comparing each object JSON one by one, between the collections was just not feasible. The risk of making a mistake between the collection items schema and each specific object schema was just to big, not to mention the tremendous effort required.
Fortunately all objets accept an id that looks like a UUIDv4. I attempted to send my own id format but no success, we need to use UUID's.
In order to create deterministic UUID's I used UUIDv5, that take a seed UUID and then can generate a UUID based on a string. If the seed, and the string are the same you'll get the same UUID, working similar to a hash.
If the objects are too big I hash them first and then generate the UUIDv5. If the size is acceptable then I generate the UUIDv5 from the JSON.stringify of the object.
All in all if the objects coming from the updated collection have the same id of the objects on the deployed collection, then they are the same.
From this point on I just create the unmatched new objects and delete the unmatched old ones.
Adjusting the deployment strategy at run time
The last step was to determine if the collection top level objects changed.
If so, then I update the collection without any items, effectively clearing all folders, requests and responses, and then proceed with the incremental step by step update.
You might be thinking, why not use the old bulk deployment?
Deploying the entire collection incrementally does take longer than the bulk deployment but I'm trying to avoid the HTTP 500 server error I sometimes get when deploying in bulk.
Initial results
Looking at our repo actions we noticed a big improvement for a common update that does not include any top level collection objects, from 7 to 1 minute and 40 seconds. Please note the 14 minutes are for 2 collections while the other deployment is for a single collection, all with the same changes.
You can take a deeper look at the code on this GitHub repo.
We didn't stop here. Using the Postman API and the pre-request scripts we were able to bring a higher level of flexibility to our collection.
Our collection now supports bearer, OAuth 2.0, Client Credential Grants (CCG), and JSON Web Tokens, authentication all at the same time, based on the type of environment selected.
This gives extra flexibility to developers to use any authentication type in multiple Box applications, and quickly switch between them.
You can check out this article:
Thoughts? Comments? Feedback?
Drop us a line on our community forum.
