Hi, Yiping, Thanks for your suggestions. I have updated the template based on your suggestions. Please find attached the updated template for your reference.
I agree with your suggestion on proof-reading the descriptions. This is an important part of ensuring effective API references. I think the developers can do a peer review of the descriptions before they create a PR for reviewing and checking in the API descriptions. I hope we will have clarity on the target release soon. Thanks, Rajsekhar On Wed, Nov 11, 2015 at 11:46 PM, Yiping Zhang <yzh...@marketo.com> wrote: > 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 > >> >
api-reference-template-version2.docx
Description: MS-Word 2007 document
