On Wed, Jan 09, 2013 at 05:34:58AM +0530, Rohit Yadav wrote:
> I've my plugin ready which can help clients discover apis if they
> want to. Will start working on implementing support for this
> feature in cloudmonkey soon.
>
> The response structure is an array of apis with: name (name of the
> api command), description (or docstring), since (version since the
> api was introduced, empty suggests it was pre 3.x), isasync (true if
> api is asynchronous), array of dictionary of params.
>
> The structure for list of params is: name (name of the parameter),
> description (or doctoring for the parameter), type (kind of
> parameter, bool, long, map, uuid etc.), length (allowed max length
> for the param, default is 255), required (if param is necessary for
> making an api request), since (CloudStack versions no. in which
> param was introduced, empty suggests it was introduced when the api
> was introduced).
>
> Example response:
>
> { "listapisresponse" : { "count":301 ,"apis" : [
> {"name":"listAsyncJobs","description":"Lists all pending
> asynchronous jobs for the
> account.","since":"","isasync":false,"param":[{"name":"pagesize","description":"","type":"INTEGER","length":255,"required":false,"since":""},{"name":"domainid","description":"list
> only resources belonging to the domain
> specified","type":"UUID","length":255,"required":false,"since":""},{"name":"listall","description":"If
> set to false, list only resources belonging to the command's caller;
> if set to true - list resources that the caller is authorized to
> see. Default value is
> false","type":"BOOLEAN","length":255,"required":false,"since":""},{"name":"account","description":"List
> resources by account. Must be used with the domainId
> parameter.","type":"STRING","length":255,"required":false,"since":""},{"name":"startdate","description":"the
> start date of the async
> job","type":"TZDATE","length":255,"required":false,"since":""},{"name":"page","description":"","type":"INTEGER","length":255,"required":false,"since":""},{"name":"isrecursive","description":"defaults
> to false, but if true, lists all resources from the parent specified
> by the domainId till
> leaves.","type":"BOOLEAN","length":255,"required":false,"since":""},{"name":"keyword","description":"List
> by
> keyword","type":"STRING","length":255,"required":false,"since":""}]}
>
> This information is pre-cached during load time (when mgmt server
> starts) as a list of response by the plugin and it takes about 677
> milliseconds to generate mapping of apiname and cmd class and 89
> milliseconds to pre cache the response object:
>
> INFO [cloudstack.discovery.ApiDiscoveryServiceImpl] (main:)
> Generated apiname, cmd class mapping in 677 ms INFO
> [cloudstack.discovery.ApiDiscoveryServiceImpl] (main:) Discovered
> api, precached response in 89 ms
>
> The plugin is an adapter, also a pluggable service and provides an
> api cmd class with apiname listApis (suggest a better name, listApis
> made sense as the response is list of Apis + docs available on the
> CS mgmt server to the user).
>
> Based on parameter annotation, we can also return information of
> related apis for a particular apis (based on response class, say all
> vm related apis have same response class) and also suggest apis to
> get the parameter (wherever applicable, we know entityType, so we
> know the response class). Do we want such a feature?
>
> Since, this is a plugin and has its own commands.properties, one can
> blacklist or change role based acl (in commands.properties) or
> disable plugin (from components.xml) to controls or use this plugin
> as a starting point to make their own discovery service (not just
> apis, think discovery of resources etc.).
>
> I want feedback on the response structure (if we want any more
> information or in some format), data structures (right now using
> only list and hash sets) and how to make a better, faster api
> discovery service.
>
> This discovery service can be used for clients, wrappers (to
> automatically wrap around api changes, I ) and to generate say an
> online apidoc for a mgmt server.
Rohit, this is pretty cool! I'll take a look at this since you seem
to have an implementation checked in on master.
I didn't see a JIRA ticket for this so I've created one with
CLOUDSTACK-926.
I've created a subtask for this to improve marvin to autogenerate its
API classes from the service endpoint. Most likely cloudmonkey and
marvin will share the same mechanism to generate the classes they need
for autocompletion on the shell and the marvin libraries.
-- Prasanna.,
