Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

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

WSO2 is the only open source vendor to be named a leader in The Forrester Wave™: API Management Solutions, Q4 2018 Report. Download the report now or try out our product for free.

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.

IAM is now more than a security project. It’s an enabler for an integration agile enterprise. If you’re currently evaluating an identity solution or exploring IAM, join this webinar.

Topics:
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 }}