For both OpenStack and Rackspace cloud APIs, we use WADL, Web Application Description Language, to build an API reference listing for all REST API calls. In a previous post, I discussed how the reference pages at http://developer.openstack.org/api-ref.html were made with a WADL source and a Maven plugin, clouddocs-maven-plugin. (Updated to add: in 2023, you would use OpenAPI Specification files rather than WADL to generate your API reference documentation. Here’s one example.)
You can see the output for the Rackspace API reference page, built with the same toolchain but different branding through CSS. I can discuss the tooling decision process in another post, but let’s talk about the ongoing upkeep and maintenance of this API reference information.
In this post, I want to dig beneath the surface to discover how complex these APIs are. That complexity translates into difficulty or time spent documenting the interfaces. So let’s discuss ways you could assign work to create and maintain reference information for APIs. In another post, I wrote that you could start with a list. This post looks into what happens after you have a list and need more lists to know the shape and size of your API and its documentation needs.
Some of the complexity also lies in documenting the parameters and headers for each API. Just like unearthing the walls of an ancient structure, you can look at the various ways an API is put together by looking at the number of calls, the number of parameters on each call, whether there are headers on any given call, and how the calls are grouped and related. I’ve summarized some below for the comparison of the APIs.
REST API Vocabulary and Definitions
A call is a GET PUT POST DELETE command sent to a resource. These are known as HTTP verbs.
A header is an optional or required component of an HTTP request or response. There are plenty of standard headers; I’m talking about the extra headers defined by the API you document specifically.
For example, a parameter may be a query parameter or provide a way to filter the response. Parameters specify a varying part of the resource, and your users need to know what parameters are available and what they can do with them.
Running the numbers
To get these numbers, I first built each reference site so that the WADL files could be built into a single folder, which lets me do a grep command for a count.
So I cloned each repo, ran mvn clean generate-sources within the api-ref directory, then ran this command from within from within the folder containing all the output, api-site/api-ref/target/docbkx/html:
grep -c “rax:id” wadls/*.wadl | sort -n -k2 -t:
Then I imported the output from the command as a colon-delimited file to a spreadsheet to get these counts.
OpenStack API Reference Metrics
Number of Compute v2.0 calls:290
Number of Networking v2.0 calls:92
Number of Orchestration v1.0 calls:41
Total documented calls:755
Rackspace API Reference
Number of Cloud Files calls:21
Number of Compute v2.0 calls:70
Number of Networking v2.0 calls:18
Total documented calls:670
Here’s a breakdown for just a few of the OpenStack APIs header and parameter counts.
Object Storage API Parameters: 12, Headers: 75
Volume API Parameters: 23 Headers: 0
Compute core API Parameters: 69 Headers: 1
Other metrics
We track doc bugs for the OpenStack API reference in Launchpad with the openstack-api-site project. There are nearly 200 doc bugs logged against the API Reference right now.
The three APIs with the most calls for Rackspace are Monitoring, Email & Apps, and Load Balancers, which are not OpenStack APIs. So a full two-thirds of Rackspace calls are not OpenStack-sourced. However, this means that a full third of Rackspace calls are identical to OpenStack.
What are some of the differences between OpenStack and Rackspace?
- Extensions are complete in OpenStack; Rackspace only implements a handful of extensions.
- Internal (admin-only) and external (user) calls are documented in OpenStack; Rackspace API Ref only documents external calls.
- Rackspace has staff API writers and accepts pull requests on GitHub. OpenStack docs are written by writers and developers in the community (often with corporate sponsors) using the OpenStack Gerrit process.
Conclusion
So that’s a lot of numbers, but what’s your point? My point is that making lists helps you determine the size and complexity of documenting multiple APIs. Not all companies or projects will have more than one API to document. Still, as we move towards more application interfaces for more business reasons, I believe that writers and developers need to get accurate in their estimations of just how much time to allocate to document their APIs and do it well.
Since these estimates are for API reference information only, don’t also fail to estimate the time to write and maintain viable, tested example code. That’s a post for another day; thanks for reading about the complexity and comparison of OpenStack and Rackspace cloud APIs.