As a user who uses API a lot, I would like to see following improvements in api reference pages:
1) In brief description for Title section, please specify if the referenced API is async or not. Currently, this info is available only on the API listing pages with “(A)” after the api name, but not available or obvious anywhere on the api reference page itself. 2) For each parameter, in addition to <Description>, <Format>, <example> attributes, it would be great to also provide following: <type> := integer | string | array | enumerate | boolean etc <default_value> := true | false | null | 0 etc A Notes subsection for parameters: IMHO, there are several reasons that such a section will be useful: * A list of values which have special meaning to the api and what are their special meanings, if any. For example, for listVirtualMachines api, projectid=-1 would return instances belonging to ALL projects. Here value “-1” is special. * combination of certain parameters are mutually exclusive, or are required. Some of this info are currently present in the parameter’s description field. But they are usually too brief, hard to read and hard to understand. 3) Add a limitations section: This section describes scenarios where the referenced API does not apply to, or not implemented yet, or known to not work properly. Many apis have limitations and the information is scattered all over places in documents, if exists at all. So most often users can only find out by trial and errors. For example, assignVirtualMachine api has following limitations: 1) does not work with VM instances belonging to a project, 2) not implemented for Advanced networking with security group enabled. 4) Add an Authorization section or just provide info on the page somewhere: describe who can make this api call: root admin, domain admin, or regular users. Currently, this info is provided by listing available apis in different pages titled “Root admin API”, “domain admin api” and “User api”. Personally, I prefer a separate section on each api’s reference page for this info so that it can’t be missed. 5) Error response: I really like the idea of adding this section to the reference page. Please list both HTTP response code as well as CloudStack internal error code and error messages. Finally, please get some one to proof-read all descriptions. Some of current API document are really hard to understand! BTW: which release is this proposal targeted for ? Just my $0.02. Yiping On 11/10/15, 9:10 PM, "Daejuan Jacobs" <daej...@gmail.com> wrote: >I assume by "Format" you mean data type. > >But I think this looks good. It's simple, yet it manages to nail all the >points you need when developing on a software's API. > >On Tue, Nov 10, 2015 at 8:33 AM Rajsekhar K <rajsekharkpa...@gmail.com> >wrote: > >> Hi, All, >> >> This is the proposal for a new template for CloudStack API reference >> pages. This template is based on the reference page templates for REST APIs. >> >> Please find attached the following documents for your review: >> >> - Template for normal and asynchronous CloudStack API references. >> - Sample API reference page using the template for a CloudStack API >> (listZones). >> >> >> Please review this template and let me know your thoughts on this. >> >> Thanks, >> Rajsekhar >>