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" <[email protected]> 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 <[email protected]>
>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
>>
