incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rohit Yadav <rohit.ya...@citrix.com>
Subject RE: [DISCUSS] CloudStack API Discovery Service
Date Wed, 09 Jan 2013 11:08:31 GMT
Hi Prasanna,

Yes, I had filed an issue for this, but the issue you filed is much better and verbose.

Resolved as fixed as this issue as it's already code complete and committed on master:
https://issues.apache.org/jira/browse/CLOUDSTACK-926

Will work on cloudmonkey this week. The plugin is an adapter and a pluggable service and provides
listApis that lists all apis with their docstring, params etc.
Not sure about marvin, on how that should work, as if marvin chooses to use the discovery
service will it still require cloudstackAPI? The other issue is that right now it does not
recommend related apis and output response info for an api, just the request info, params
etc. Do we want that, I asked couple of question, would like to know your views on it as marvin
maintainer you'll have more knowledge on the library usage?

Thanks!
Rohit

________________________________________
From: prasanna [srivatsav.prasanna@gmail.com] On Behalf Of Prasanna Santhanam [tsp@apache.org]
Sent: Wednesday, January 09, 2013 3:45 PM
To: cloudstack-dev@incubator.apache.org
Subject: Re: [DISCUSS] CloudStack API Discovery Service

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.,

Mime
View raw message