Improved API Documentation

June 8, 2017 · by Mike Sierra

I thought I'd let you know of some of the great things we're doing for API documentation.

You should now be seeing improvements in accuracy and consistency across the board. Originally, Akamai's API effort was led by developers, who provided much of the accompanying documentation. Unfortunately, different teams of developers had much different ideas about what to include in documentation. They also used much different sets of terminology.

Technical writers now lead on API documentation, and we've worked to develop better editorial standards. We now focus more on the distinct challenges that APIs pose to the subset of our customers who are developers.

For example, when you go to a user interface such as the Luna portal, you toggle some options or make selections from popup lists, then you press DONE. But what if it were possible to press that button... incorrectly? That's the unique challenge of API doc.

The lower-level details you need to negotiate with each API, and the variations in how these APIs behave, are often far more immediately relevant than the set of functionality each API enables. Whether the API performs rate limiting, or if it enables asynchronous calls, or versions its data objects, all matter in ways that never become apparent in a user interface.

We're retooling around RAML as our API descriptor language. You may notice these source files are available for download on the Resources page for newly released APIs. Unlike Apiary Blueprint's looser markdown-based content format, RAML parses more rigorously as a data structure, which means we can validate its contents better, and there's much greater opportunity to synchronize with source code. (We also considered Swagger, which is roughly equivalent to RAML, but is expressed in JSON rather than YAML.)

Documentation now generates directly from these RAML source files. For some of our faster-moving APIs, this means we can quickly update doc in response to newly available endpoints, parameters, data objects, and enumerated values. Look for more tooling in the future that will allow you to integrate these RAML files into your development workflow.

We've also worked to improve our overall documentation interface. To get information about each operation, you used to have to select an API interface from the API product, then select an endpoint, then the method you want to call on that endpoint. We've now changed it to push the list of the API operations you actually use to the top-most level.

Our tabbed interface also makes different facets of each API operation much more accessible. It especially helps to clarify when APIs produce different types of success response, distinguished either by the status code or the content type. Here's how it looks:

Along with RAML, we're consistently using JSON Schema to describe all the data structures our APIs exchange, available in the Data tab alongside Resources in each API's documentation set. Earlier APIs often didn't document data structures at all, and you had to guess how it worked based on sample data.

To avoid some of the complexities of JSON Pointer expressions, we're using a simple form of notation to tabulate each object's structure, either parent.child for nested objects, or parent.children[n] for arrays of objects, which covers most cases. To ensure the highest accuracy, our tools now generate documentation directly from Draft 4 schema, and also wherever possible leverage hyperschema specifying JSON members that are readOnly:

For the future, we're working to improve our tools to better represent some more complex facets of these data objects. For example, different membership requirements may apply depending on the interaction context (such as POST vs. PUT), or for different MIME versions of an object. Look for such improvements in future API doc. You can also expect improvements for how all other documentation is presented at Akamai. Please let us know what you think, and we always welcome any feedback!