cloudstack-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Dunaway <dave.duna...@gmail.com>
Subject Re: Improving API reference pages
Date Mon, 03 Aug 2015 13:24:15 GMT
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 <rajsekharkpally@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message