On Wed, Jan 09, 2013 at 04:38:31PM +0530, Rohit Yadav wrote:
> 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?
Not quite - I propose to build the cloudstackAPI from the endpoint's
list of supported APIs.
> 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?
I see now that the response structure is missing. Related APIs I don't
see a usecase for within marvin however.
cloudmonkey only has to present the json response formatted to the
user so the actual response object isn't really useful for it.
whereas marvin needs to unmarshall back the response from the plain
json to make sense of it. this should be true for any other client
library doing further processing when dealing with our API.
For it to be truly a web-service discovery mechanism I think it should
return the response as well.
A further question I had was regarding the role of the user making the
listApis call. Haven't dug into the implementation yet - so I'll ask
anyway. Does the listApis return the full list of APIs or honor the
role of the user requesting for his/her callable set of APIs on the
specified endpoint?
--
Prasanna.,
>
> Thanks!
> Rohit
>
> ________________________________________
> From: prasanna [srivatsav.prasa...@gmail.com] On Behalf Of Prasanna Santhanam
> [t...@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.,
