Glad you asked! The site at http://api.openstack.org is a collection of HTML pages, and one page has an especially interesting story about how it is built. The http://api.openstack.org/api-ref.html page provides a listing of all the API calls for all OpenStack APIs that contribute docs to the page. Currently the only API that is still a work in progress is the Networking API, but here’s a patch in review and they soon will be included also.
The page has a lot of Javascript and CSS, DocBook and XSLT, XML and JSON behind it, which enables a few cool features. One is the details button, which gives an expanded set of information after you click it. Another cool feature is the ability to display either XML or JSON examples for the request or response with a drop-down list, and you can choose which to show by default. I also like the in-page search, which is more powerful than just using the browser’s page search feature because it digs deeper into the descriptions, expands to show any hits on your keywords in required and optional parameters, and in the response and requests codes. It highlights the found terms after expanding. Another cool aspect of the page is that all the Compute API samples are tested against a gate using code in the nova repository. Tested samples have been added in meticulously by Laura Alves, an awesome doc intern, with additional thanks to Sean Dague and his cohorts poking nova developers during the last dev cycle to ensure we have test samples for all API calls.
I believe there’s a lot of value in a long listing of reference information for the OpenStack APIs, and I’m glad Joe Heck took the initiative to get a blueprint going for it. David Cramer, Joe Savak, and Thu Doan at Rackspace took the blueprint and made it a reality with the Maven plugin at clouddocs-maven-plugin. The original goal of the page was to provide an all-in-one listing of all the API calls you could make against OpenStack services. At the time there were 3 or 4 services. Now we could potentially have 9 services with both admin-level API calls and end-user API calls, not to mention the extensions across 3 or 4 of the 9 services. So we are revisiting the all-in-one design of the page. Another aspect of the page is that it’s the only place to get documentation for the Compute extensions right now and the only site with tested examples without spelunking the code itself.
So, how’s it made? The basic building blocks of the page are:
- WADL files – Web Application Description Language, a proposed Wc3 standard in XML used for describing REST APIs, read all about it in the specification at http://www.w3.org/Submission/wadl/. Here’s an example with the Image API 1.0 WADL.
- XML files – Sample requests and expected responses. For Compute, these are copied right from the repository and each code submission that has an API piece must contian templates that build the example. Here’s a sample file: userdata-post-req.xml.
- JSON files – Sample requests and expected responses. Here’s a sample file: userdata-post-req.json.
- DocBook file – DocBook is an established documentation XML standard. Here it’s used as overarching XML organizing file, you can see it at api-ref.xml.
With these building blocks assembled in the openstack/api-site repository, you must also have a pom.xml to make the Maven plugin build the resulting api-ref.html page. The pom.xml is called by a Jenkins job maintained in the openstack-infra/config repository in a .yaml file. To build it yourself locally, install Maven and then do:
git clone git://github.com/openstack/api-site.git cd api-site/api-ref mvn clean generate-sources
Wait a while (maybe even 15 minutes first run) for the build to get all the dependencies it needs, then when you see BUILD SUCCESS, open the api-ref.html file in the target/dockbkx/html/ directory and revel in all the features listed above. If you want to submit a change, use the Gerrit workflow all the OpenStack projects use.
The backlog of bugs for this page is maintained at http://bugs.launchpad.net/openstack-api-site. If you see a mistake or want to ask for a addition, feel free to log a bug there. Laura Alves, our GNOME Outreach Program for Women intern, did an excellent job this past three months maintaining the page. My fellow Racker Diane Fleming is currently doing doc bug triage and fixing for the page as well. Future plans include adding a navigation layer on top of the page so it’s not one long page, but lets you pick the API for the service you’re interested in. With the additional APIs and new versions, we definitely want to keep updating the design as the APIs themselves grow and mature. Feel free to join in the API fun.
