Introduction

Purpose

The CloudStack API references  do not adequately communicate the details of the APIs. This inadequacy of information seems to have affected the user experience of CloudStack APIs.

The purpose of this document is to suggest methods to improve the CloudStack API references. Improved CloudStack API references that adequately describe APIs help users educate themselves about the purpose and usage of the APIs. This knowledge helps them make appropriate decisions when using CloudStack.

References

TBD

Document History

Feature Specifications

The new template that is defined for the CloudStack API describes the information that an ideal CloudStack  API reference should contain. Also, this document describes the technical aspects of generating an improved CloudStack API references.

The current CloudStack API references contain the following information:

• Name of the API, which is the label of the API reference page

• Description on the purpose of the API in a single line

• List of request parameters, their single-line descriptions, and information on whether these parameters are mandatory. This information has been documented in a table.

• List of response tags and their single-line descriptions. This information has been documented in a table.

Current Method of Creating/Generating API References

CloudStack uses Java docs for creating API references. The developer who creates an API enters the descriptions in the @ APICommand annotation field in the code. Finally, the API references are generated from the code.

Limitations:

The following are the limitations of the current CloudStack API references:

• All the information about an API are not documented

• Descriptions are inadequate to explain the purpose and usage of the API. They are mostly single-line descriptions

• No information on the structure of the request URL. Also, no example for the request URL.

• No information on the success response

• No information on the error response

• No information on the limitations of an API

The proposal

The CloudStack API references miss many pieces of information that are crucial for ensuring an excellent user experience. The proposed template for the CloudStack API reference in Appendix A helps you understand these additional information to be documented for CloudStack API references.

This document does not suggest any major changes to our current approach for creating/generating API references. The developers will continue adding content in the @APICommand annotation fields when they create an API. The template in Appendix A can guide them in determining the information that they need to add to @APICommand annotation fields.

Also, this document proposes Tech Pubs review of the API reference page before publishing the API references.

Implementing the New Template for API References

The following figure delineates the workflow for the generation of API docs from the code:

• The APIXMLWriter.java file plays an important role in creating API reference pages. This file collects data from @APICommand annotations of each API and stores in a .xml file. The API references in HTML format have been created from this .xml file as described in the diagram.

• Need to modify the .css file to make any modification in the way the content is displayed on the HTML pages.

Challenges

• Currently, the @APICommand annotation fields in the code are optional. To make some of the @APICommand annotation fields mandatory, each file needs be modified. Otherwise, this will cause a build failure.

Appendix

Appendix A

The proposed template for the CloudPlatform API (MS Word format):