You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Rajsekhar K <ra...@gmail.com> on 2015/11/10 15:33:13 UTC
[Proposal] Template for CloudStack API Reference Pages
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
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Rajsekhar K <ra...@gmail.com>.
Thanks.
Format is to domonstrate the usage of the API. I think that the format
along with an example would help users understand how they can use the API.
For example, the migrateto parameter in the API has the following format:
migrateto[volume-index].volume=<uuid>&migrateto[volume-index].pool=<uuid>Where,
[volume-index] indicates the index to identify the volume that you want to
migrate, volume=<uuid> indicates the UUID of the volume that you want to
migrate, and pool=<uuid> indicates the UUID of the pool where you want to
migrate the volume.
An example for this format is:
migrateto[0].volume=<71f43cd6-69b0-4d3b-9fbc-67f50963d60b>&migrateto[0].pool=<a382f181-3d2b-4413-b92d-b8931befa7e1>&migrateto[1].volume=<88de0173-55c0-4c1c-a269-83d0279eeedf>&migrateto[1].pool=<95d6e97c-6766-4d67-9a30-c449c15011d1>&migrateto[2].volume=<1b331390-59f2-4796-9993-bf11c6e76225>&migrateto[2].pool=<41fdb564-9d3b-447d-88ed-7628f7640cbc>
Thanks,
Rajsekhar
On Wed, Nov 11, 2015 at 10:40 AM, Daejuan Jacobs <da...@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 <ra...@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
> >
>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Rajsekhar K <ra...@gmail.com>.
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 <yz...@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" <da...@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 <ra...@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
> >>
>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Rajsekhar K <ra...@gmail.com>.
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 <yz...@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" <da...@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 <ra...@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
> >>
>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Yiping Zhang <yz...@marketo.com>.
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" <da...@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 <ra...@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
>>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Rajsekhar K <ra...@gmail.com>.
Thanks.
Format is to domonstrate the usage of the API. I think that the format
along with an example would help users understand how they can use the API.
For example, the migrateto parameter in the API has the following format:
migrateto[volume-index].volume=<uuid>&migrateto[volume-index].pool=<uuid>Where,
[volume-index] indicates the index to identify the volume that you want to
migrate, volume=<uuid> indicates the UUID of the volume that you want to
migrate, and pool=<uuid> indicates the UUID of the pool where you want to
migrate the volume.
An example for this format is:
migrateto[0].volume=<71f43cd6-69b0-4d3b-9fbc-67f50963d60b>&migrateto[0].pool=<a382f181-3d2b-4413-b92d-b8931befa7e1>&migrateto[1].volume=<88de0173-55c0-4c1c-a269-83d0279eeedf>&migrateto[1].pool=<95d6e97c-6766-4d67-9a30-c449c15011d1>&migrateto[2].volume=<1b331390-59f2-4796-9993-bf11c6e76225>&migrateto[2].pool=<41fdb564-9d3b-447d-88ed-7628f7640cbc>
Thanks,
Rajsekhar
On Wed, Nov 11, 2015 at 10:40 AM, Daejuan Jacobs <da...@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 <ra...@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
> >
>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Yiping Zhang <yz...@marketo.com>.
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" <da...@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 <ra...@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
>>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Daejuan Jacobs <da...@gmail.com>.
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 <ra...@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
>
Re: [Proposal] Template for CloudStack API Reference Pages
Posted by Daejuan Jacobs <da...@gmail.com>.
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 <ra...@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
>