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

Discover how Microservices are a type of software architecture where large applications are made up of small, self-contained units working together through APIs that are not dependent on a specific language. Brought to you in partnership with AppDynamics.

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.

Discover the six challenges and best practices in managing microservice performance, brought to you in partnership with AppDynamics.

Topics:
api ,api documentation ,integration ,api operations

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

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

{{ parent.tldr }}

{{ parent.urlSource.name }}