The Abiquo wiki now contains fully automated Abiquo API reference documentation. Prior to the release of these new API docs, a previous version of automated reference documentation was manually maintained on the Abiquo wiki.
The Automated REST API Examples project added basic request examples for the Abiquo API reference documentation from 2016 to 2019 before the examples were included in the new API docs. Abiquo is an IaaS cloud management platform and the Abiquo API has over 100 resources and over 700 methods. Support staff required API examples because they work with more than one version of the product at a time, and they may need to quickly switch between versions. And external developers can use the API examples to easily gain an overview of the product so as to better design integrations.
The Abiquo REST API is HATEAOS, which means that users should navigate it using links, and dependent objects may also be defined using contextual links. For example, a link to a disk object defines the disk in a VM. Moreover, in the Abiquo cloud platform, many objects have dependencies, for example, before you launch a VM, you need to create a datacenter or public cloud region, and then a virtual datacenter for the cloud user to work in. And when you create a virtual datacenter, you need to supply a link to the cloud location where the VM will run. So documentation about links is important not just for navigation but also for creating objects.
The links that the Abiquo API uses are complex with four components: a URL, a media type, a relation, and a title. The API documentation had little coverage of links and there were no popular documentation automation solutions that supported links when I began this project in late 2015. In fact, popular API documentation automation solutions still don't provide the level of support for links that Abiquo requires and for this reason, Abiquo uses a custom solution. For a simple example containing links from the current documentation, see https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#create-a-metric-metadata-on-a-virtual-machine.
The Abiquo integration tests cover the majority of the methods available in the Abiquo API. A developer generated a request log file in JSON format as part of the build. Then I wrote some simple Python scripts to prepare the request examples and add them to the Abiquo wiki.
The first Python script processed the log file and selected the successful and appropriate requests by status code and other criteria. The output from this step was a series of example files in the local file system. The script named the files with an abbreviation of the request methods and media types. For example, the script abbreviated the example request to retrieve an enterprise in JSON format as GET_adm_ents_X_AC_ent_j and added a sequence number to identify multiple successful requests for each query. The second Python script took the list of example files to publish and created or updated a separate wiki page for each example.
To initially add the examples to the API reference documentation, I manually edited the section for each API method and inserted the example using an Include page macro. This manual process gave me the opportunity to review each example and check for issues, such as weird test data or empty lists, in which case I could manually select another example file. It was then easy to update the example pages for each release and to compare examples between versions.
As Abiquo 4.4 was deprecated some time ago, a single API example page can still be found at: https://abiquo.atlassian.net/wiki/spaces/doc/pages/311365923/POST+cld+vdcs+X+vapps+X+vms+X+collectd+CT+app+j
The new API docs for this endpoint are at: https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#push-collectd-values-on-a-virtual-machine. The new API docs display details of the most commonly used links in each resource that are extracted from the integration test results.
The Python scripts can be found in my GitHub account (mjsmyth) in the abiquo-wiki-examples repository.
With over 700 examples, this automation project enabled me to easily maintain a large volume of documentation that made life easier for the Support team and made the Abiquo API more accessible to new users.