Introduction

CloudStack has over 300 APIs and in each release we end up adding bunch of them. A CloudStack admin can enable/disable these APIs and add a plugin which can add few more APIs. API Discovery Service is a plugin which helps discover role based APIs available on a CloudStack management server.

Implementation

The discovery service implements a method called listApis which should return information about APIs for a user, rightnow it accepts an apiName to list api information of that particular API. The method ensures that user can only list APIs they are entitled to.

public interface ApiDiscoveryService extends PluggableService {
    ListResponse<? extends BaseResponse> listApis(User user, String apiName);
}

The present implementation is in form of a plugin in plugin/api/discovery. The API discovery happens during load time when the management server is starting which is because CloudStack does not allow runtime plugin loading, so it made sense to discovery and cache API information during load time, this also makes listApis call really fast.

All CloudStack APIs are implemented by annotated command class and PluggableService is a contract implemented by all the components such as the ManagementServer and all the plugins which provide an API. During load time, API discovery service asks all the pluggable services to return list of API cmd classes from whose fields and annotations it gathers information about each API, the information consists of name, description, parameter name, parameter description etc. The whole process takes less than a second and we can see messages like following in CloudStack's mgmt server logs:

2013-03-06 18:48:45,160 INFO  [cloudstack.discovery.ApiDiscoveryServiceImpl] (main:null) Api Discovery Service: Annotation, docstrings, api relation graph processed in 491.386 ms

This was implemented for 4.1 and starting 4.1 release all versions will have the discovery service which is enabled by default. We chose to enable it by default because it made sense to provide a user list of APIs they can call.

Response

The listApis command results in list of API with their name, description, request params and response fields. For example listApis response for the listApis itself in xml:

<listapisresponse cloud-stack-version="4.2.0-SNAPSHOT"><count>1
</count><api><name>listApis
</name><description>lists all available apis on the server, provided by the Api Discovery plugin
</description><since>4.1.0
</since><isasync>false
</isasync><related/><params><name>name
</name><description>API name
</description><type>string
</type><length>255
</length><required>false
</required>
</params><response><name>params
</name><description>the list params the api accepts
</description><type>set
</type>
</response><response><name>response
</name><description>api response fields
</description><type>set
</type>
</response><response><name>related
</name><description>comma separated related apis
</description><type>string
</type>
</response><response><name>since
</name><description>version of CloudStack the api was introduced in
</description><type>string
</type>
</response><response><name>isasync
</name><description>true if api is asynchronous
</description><type>boolean
</type>
</response><response><name>description
</name><description>description of the api
</description><type>string
</type>
</response><response><name>name
</name><description>the name of the api command
</description><type>string
</type>
</response>
</api>
</listapisresponse>

Users

At present cloudmonkey, the CloudStack CLI uses this discovery feature to automatically generate a domain specific language (DSL) grammer, verbs and subjects. cloudmonkey provides an operation called "sync" to fetch the API information and which is then processed and cached, for more information: https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI#CloudStackcloudmonkeyCLI-Gettingstarted

In future, this service can be used by cloud-engine, the core orchestrating engine to publish APIs of several of its components on the fly and cloudmonkey can generate DSL for all of them on the fly.

  • No labels