cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Yiping Zhang <yzh...@marketo.com>
Subject Re: [Proposal] Template for CloudStack API Reference Pages
Date Wed, 11 Nov 2015 18:16:39 GMT
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" <daejuan@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 <rajsekharkpally@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
>>
Mime
View raw message