Box transforms API onboarding with Postman automation tools

Box APIs allow businesses to deeply integrate Box into their daily operations. Whether these businesses are building customer-facing applications, internal workflow automation, or data synchronization systems, Box APIs enable seamless connection to the Box Platform. Users can choose from a wide range of available APIs such as file versioning, user authentication, and storage policy management.

The Box Developer Relations team supports the Box user community with API documentation, training, and tools to help them quickly get started building customizations. Box API users span a range of technical backgrounds, and some users have limited access to technical resources. Most users fall into two broad categories:

1. Box administrators doing workflow automation: Box admins sit within IT and manage their company's Box instance. Often, they'll write scripts that use Box APIs to automate repetitive tasks, such as account creation and configuration, or time-consuming workflows, such as bulk user-provisioning and folder setup. Although the Box UI provides templates for some tasks, Box APIs fill in the gaps. Admins use Box's Postman Collection to help them customize their automations. They can easily discover and access the requests they need, as well as save and repurpose responses within their Postman workspace.
2. Developers doing exploratory testing: Developers use Box APIs to build applications and solutions that integrate seamlessly with Box, third-party SaaS platforms, and in-house systems. Development teams may be tasked to build entire integrated experiences on top of Box that expose files and folders in Box through custom interfaces. Often, these developers use Box's Postman Collection to test out Box APIs and get a better understanding of their components and capabilities before they start writing code. The collection helps them validate assumptions early in development, keeping the project moving forward and on track.

Box's original Postman Collection was built by a small team who eventually moved on to new roles, and without regular maintenance, the collection became outdated. New APIs were not included in the collection, and the user experience needed an overhaul. By the time the Developer Relations team took ownership of the collection, Box was considering dropping the collection altogether. However, usage had remained steady and one message came through loud and clear from customers: they wanted to use Postman.

“Postman is a favorite tool of our user community. We decided to relaunch our Postman Collection and onboarding experience based on customer demand.”

Cristiano Betta, Senior Developer Advocate, Box

In early 2019, the Box Platform organization kicked off a new initiative to rebuild its developer documentation to better align with industry best practices. Part of this project involved improving Box's public OpenAPI specification, and by mid-year, the team had launched a brand new 3.0 version from which they could build their API reference documentation. After investing significant time and resources into rebuilding the OpenAPI specification, they wanted to maximize its value by looking for ways to leverage it in downstream dependencies. Box's Postman Collection emerged as the perfect opportunity for alignment. Not only could the Developer Relations team use the new specification to bring the Box API collection up to date, but they could build an automation tool to keep it updated and thus address one of the toughest hurdles for the team.

The Postman API enables automatic updates to the Box API collection.

The Developer Relations team got to work on overhauling the Postman Collection. First, they designed a new folder structure that groups API calls into folders by topics, making it easier to find the right API endpoints. Next, the team built their own open source automation tool that would update their Postman Collection every time the Box API specification changed. The tool uses pre- and post-request scripts and the Postman API's Update Collection endpoint to update the collection and upload a new version to their site. As a result of this automation, Box's Postman Collection is now easier to maintain and more valuable to users.

“Our API reference updates used to take weeks or fall through the cracks. Now, it takes minutes. Whenever our OpenAPI 3.0 specification changes, the Postman API automatically updates our Postman Collection.”

Cristiano Betta, Senior Developer Advocate, Box

With the success of their auto-updater, the Developer Relations team next focused on user authentication.

Automating user authentication between Box and Postman

When users get started with Box APIs, they first set up a Box app and authenticate themselves using OAuth 2.0. Next, they use a Run in Postman button to load the Postman Collection into the Box app and then load their API credentials into Postman as an environment using a Box API access token. At this point, users are fully set up to make API calls.

As the Developer Relations team reviewed the authentication workflow, they honed in on a major pain point for users: session length. By default, the Box API access token is only valid for one hour. This meant that after 60 minutes, users would have to stop working and take manual steps to reconfigure their Postman app in order to continue.

To reduce friction for users, the Developer Relations team built new functionality using environment variables and scripts in Postman. The team wrote pre-request and test scripts that automatically detect when a user's access token is about to expire and then refresh the token for the user before the next API call is performed. Users can toggle the environment variable between automatic or manual refresh per their preference. With this feature, users can stay authenticated without interruption indefinitely, helping them stay productive and engaged with the Box APIs.

“Postman's automation tools enabled us to build a critical new feature that greatly improves the user authentication experience.”

Cristiano Betta, Senior Developer Advocate, Box

In addition to these user authentication enhancements, the Developer Relations team built a comprehensive quick start guide that walks users through setup on both the Box and Postman platforms. Together, the guide, the improved authentication, and the revitalized collection offer a greatly improved onboarding experience for the Box API user community.

In addition to these user authentication enhancements, the Developer Relations team built a comprehensive quick start guide that walks users through setup on both the Box and Postman platforms. Together, the guide, the improved authentication, and the revitalized collection offer a greatly improved onboarding experience for the Box API user community.

The Box team, and their customers, now work smarter

Box's renewed focus on optimizing its use of Postman is paying off. After relaunching their collection, and the rollout of other initiatives discussed above, the Developer Relations team has seen two key results:

1. Automation saves the team time and resources: The team no longer relies on a manual process to update their Postman Collection. Now, automated updates to the Box API collection happen continually in real time, and the team is free to focus on other initiatives.
2. Improved onboarding reduces support overhead: With access to the latest API reference and streamlined authentication, fewer users depend on support teams to help them get started with Box APIs.

Going forward, the Developer Relations team is working on further refining their Postman Collection. For example, they plan to add variations of API endpoints that provide users with pre-configured versions of existing requests to perform specific tasks, like creating app users, managing shared links, and moving files and folders. Thanks to the new auto-updater tool, as soon as these endpoints are released, the Box API collection will be updated and available to all.