cloudstack-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajsekhar K <rajsekharkpa...@gmail.com>
Subject Re: [Proposal] Template for CloudStack API Reference Pages
Date Thu, 19 Nov 2015 08:58:00 GMT
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 <yzhang@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" <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