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