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.