Box Transforms API Onboarding with Postman Automation Tools
Content is crucial to enterprise business processes. Documents, data, and an array of file types keep customers engaged and move the business forward. Over 97,000 companies around the world, including 68% of the Fortune 500, use Box to drive secure content management and collaboration across the business. With such a massive footprint, Box fuels a thriving ecosystem of developers and partners who are building new ways to leverage Box in their applications and systems. At the heart of Box customer innovation lies a robust portfolio of APIs on the Postman API Platform.
Box had been delivering its APIs on Postman for years. However, over time (and without regular maintenance) their Postman Collectionbecame outdated, which impacted customer onboarding. A new initiative prompted the Developer Relations team to redesign and relaunch their comprehensive collection, making it even easier for anyone to make their first API call in less than 10 minutes.
Postman Collections, Variables, Scripts, Run in Postman Button
Box APIs power a broad range of IT and engineering use cases
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:
- 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.
- 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 needed a better way to maintain their Postman Collection
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.
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.
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.
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:
- 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.
- 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.
More Case Studies
"Using variables in Postman helps me avoid the pain of having to duplicate data across all our requests. Instead, I can spend that time doing more valuable tasks."
Paul Farrell, Test Automation Lead
"I know developers love to test first and read later, so my goal is to help developers make test calls within five minutes and become successful. They want to get up and running right away"
Vu Nguyen, Envestnet | Yodlee