Over a million developers have joined DZone.

Box's Seamless Approach To API Documentation

DZone's Guide to

Box's Seamless Approach To API Documentation

We'll never see things move as fast as we want—but eventually, the world evolves. We'll see investment in areas that make a difference on the ground at API operations.

· Integration Zone ·
Free Resource

The new Gartner Critical Capabilities report explains how APIs and microservices enable digital leaders to deliver better B2B, open banking and mobile projects.

The document platform Box updated their developer efforts recently, helping push forward the definition of what API documentation can be. I've long been advocating moving APIs out from the shadow of the developer portal making them more seamless with any UI, kind of like CloudFlare does with their DNS dashboard. There is no reason the API should have to be hidden from users — it should be right behind the UI for everyone to discover.

Box does this. You can interact with files just like it is the regular interface. When you push get the folder items, upload file, or any other option available to you in the documentation, you get an example API request and response in the right-hand column. It is a blend of a regular UI and some of the attractive and interface documentation we've seen emerge lately, like ReDoc — making it easy to see and understand what an API does, while speaking in the context of solving a relevant problem for a human.

API documentation doesn't have to be overly technical and boring. It can look like a regular user interface, and the API can be right behind the UI curtain, providing a snapshot of the requests and responses that are doing the heavy lifting behind. I'm finally seeing the movement I have wanted to see with API documentation in 2017. I'm feeling like this is going to be a common theme in the world of APIs for all of us. We will never see things move as fast as we want, but eventually, the world evolves — and we will see investment in the areas that make a difference on the ground at API operations and for the consumers who are putting APIs to work in their regular world.

The new Gartner Critical Capabilities for Full Lifecycle API Management report shows how CA Technologies helps digital leaders with their B2B, open banking, and mobile initiatives. Get your copy from CA Technologies.

api ,api documentation ,integration ,api operations

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}