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/08/03 11:37:02 UTC
Improving API reference pages
Hi, All,
This is part of our effort to improve user experience of
Cloudstack/CloudPlatform API reference pages.
Majority of the CloudStack/CloudPlatform API reference pages do not
adequately describe the usage of the parameters associated with them. Many
of these parameters contain only a single line description, which does not
really enhance the user's experience with these APIs.
CloudPlatform had received a few documentation tickets on this, with
requests to improve the description, add information on the format, and an
example on how to use the parameter. One of the tickets was on the
*migrateto *parameter in the *migrateVirtualMachineWithVolume* API
reference page. We have improved the description of the *migrateto *parameter
as follows:
*Parameter*
*Description*
*Required*
*migrateto*
Storage to pool mapping. This parameter specifies the mapping between a
volume and a pool where you want to migrate that volume. Format of this
parameter:
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. Example:
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>
False
(This will be updated in the *migrateVirtualMachineWithVolume* API
reference page of CloudStack soon.)
I think I can take this as a base and improve the descriptions of the
parameters in the CloudStack/Cloudplatform API reference pages. As an
initial step, I have identified the following 20 API functions and I am
planning to improve the description of the parameters in their reference
pages:
-
*listAccounts *
-
*listCapacity *
-
*listLoadBalancerRules *
-
*listNetworks *
-
*listPublicIpAddresses *
-
*listSnapshots *
-
*listTemplates *
-
*listVirtualMachines *
-
*listVolumes *
-
*listZones *
-
*stopVirtualMachine *
-
*associateIPAddress *
-
*attachVolume *
-
*createSnapshot *
-
*startVirtualMachine *
-
*deployVirtualMachine *
-
*migrateVirtualMachineWithVolume *
-
*login *
-
*logout *
- *updateVirtualMachine*
Could you please provide your thoughts on this suggestion? Also, please let
me know how you can help/contribute in this effort.
Regards,
Rajsekhar
Re: Improving API reference pages
Posted by Dave Dunaway <da...@gmail.com>.
I would definitely say this is needed. A few calls need to specify "types"
of which there is not description or they are poorly worded.
If the API doc page could have comments... that would be good too. Let the
community add examples or suggestions.
However the real deal is to document the attributes and return values for
each call. Show a basic call using curl. Describe what the call does (some
have no description). Like what most other sites with API's do :)
Here's a "style" guide for API documentation creation... it seems pretty
good.
http://blog.parse.com/learn/engineering/designing-great-api-docs/
HTH
dave.
On Mon, Aug 3, 2015 at 5:37 AM, Rajsekhar K <ra...@gmail.com>
wrote:
> Hi, All,
>
> This is part of our effort to improve user experience of
> Cloudstack/CloudPlatform API reference pages.
>
> Majority of the CloudStack/CloudPlatform API reference pages do not
> adequately describe the usage of the parameters associated with them. Many
> of these parameters contain only a single line description, which does not
> really enhance the user's experience with these APIs.
>
> CloudPlatform had received a few documentation tickets on this, with
> requests to improve the description, add information on the format, and an
> example on how to use the parameter. One of the tickets was on the
> *migrateto *parameter in the *migrateVirtualMachineWithVolume* API
> reference page. We have improved the description of the *migrateto
> *parameter
> as follows:
>
> *Parameter*
>
> *Description*
>
> *Required*
>
> *migrateto*
>
> Storage to pool mapping. This parameter specifies the mapping between a
> volume and a pool where you want to migrate that volume. Format of this
> parameter:
>
> 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. Example:
>
> 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>
>
> False
>
> (This will be updated in the *migrateVirtualMachineWithVolume* API
> reference page of CloudStack soon.)
>
> I think I can take this as a base and improve the descriptions of the
> parameters in the CloudStack/Cloudplatform API reference pages. As an
> initial step, I have identified the following 20 API functions and I am
> planning to improve the description of the parameters in their reference
> pages:
>
>
> -
> *listAccounts *
> -
> *listCapacity *
> -
> *listLoadBalancerRules *
> -
> *listNetworks *
> -
> *listPublicIpAddresses *
> -
> *listSnapshots *
> -
> *listTemplates *
> -
> *listVirtualMachines *
> -
> *listVolumes *
> -
> *listZones *
> -
> *stopVirtualMachine *
> -
> *associateIPAddress *
> -
> *attachVolume *
> -
> *createSnapshot *
> -
> *startVirtualMachine *
> -
> *deployVirtualMachine *
> -
> *migrateVirtualMachineWithVolume *
> -
> *login *
> -
> *logout *
> - *updateVirtualMachine*
>
> Could you please provide your thoughts on this suggestion? Also, please let
> me know how you can help/contribute in this effort.
>
> Regards,
> Rajsekhar
>
Re: Improving API reference pages
Posted by Dave Dunaway <da...@gmail.com>.
I would definitely say this is needed. A few calls need to specify "types"
of which there is not description or they are poorly worded.
If the API doc page could have comments... that would be good too. Let the
community add examples or suggestions.
However the real deal is to document the attributes and return values for
each call. Show a basic call using curl. Describe what the call does (some
have no description). Like what most other sites with API's do :)
Here's a "style" guide for API documentation creation... it seems pretty
good.
http://blog.parse.com/learn/engineering/designing-great-api-docs/
HTH
dave.
On Mon, Aug 3, 2015 at 5:37 AM, Rajsekhar K <ra...@gmail.com>
wrote:
> Hi, All,
>
> This is part of our effort to improve user experience of
> Cloudstack/CloudPlatform API reference pages.
>
> Majority of the CloudStack/CloudPlatform API reference pages do not
> adequately describe the usage of the parameters associated with them. Many
> of these parameters contain only a single line description, which does not
> really enhance the user's experience with these APIs.
>
> CloudPlatform had received a few documentation tickets on this, with
> requests to improve the description, add information on the format, and an
> example on how to use the parameter. One of the tickets was on the
> *migrateto *parameter in the *migrateVirtualMachineWithVolume* API
> reference page. We have improved the description of the *migrateto
> *parameter
> as follows:
>
> *Parameter*
>
> *Description*
>
> *Required*
>
> *migrateto*
>
> Storage to pool mapping. This parameter specifies the mapping between a
> volume and a pool where you want to migrate that volume. Format of this
> parameter:
>
> 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. Example:
>
> 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>
>
> False
>
> (This will be updated in the *migrateVirtualMachineWithVolume* API
> reference page of CloudStack soon.)
>
> I think I can take this as a base and improve the descriptions of the
> parameters in the CloudStack/Cloudplatform API reference pages. As an
> initial step, I have identified the following 20 API functions and I am
> planning to improve the description of the parameters in their reference
> pages:
>
>
> -
> *listAccounts *
> -
> *listCapacity *
> -
> *listLoadBalancerRules *
> -
> *listNetworks *
> -
> *listPublicIpAddresses *
> -
> *listSnapshots *
> -
> *listTemplates *
> -
> *listVirtualMachines *
> -
> *listVolumes *
> -
> *listZones *
> -
> *stopVirtualMachine *
> -
> *associateIPAddress *
> -
> *attachVolume *
> -
> *createSnapshot *
> -
> *startVirtualMachine *
> -
> *deployVirtualMachine *
> -
> *migrateVirtualMachineWithVolume *
> -
> *login *
> -
> *logout *
> - *updateVirtualMachine*
>
> Could you please provide your thoughts on this suggestion? Also, please let
> me know how you can help/contribute in this effort.
>
> Regards,
> Rajsekhar
>