REST API Server Architecture

Problem

Current CloudStack API layer design suffers from various issues:

• not REST compliant, and mixed use standard GET and POST method.
• Resource response object definition is driven by UI rather from end-user perspective, causing performance issues for large scale system.
• Lack of a generic mechanism to develop new APIs, leading to inconsistent implementation in different commands.
• No standard way to perform flexible search against CloudStack entities.
• Tightly coupling ACL checking in our query logic.
  To address those issues, we are proposing to deprecate current api and api server, and redesign a REST compliant api server using JAX-RS(i.e. Apache CXF) or better technologies. This API server should be a separate component from cloud-engine and can be hosted on distributed machines to serve end-user request. Note that this new API server will only handle end-user API. Admin can request information through cloud-engine API.

REST API Server Architecture

The position of new API server in CloudStack can be depicted in the following diagram, and it has such major features:

1. API server will have its own war file to deploy as a separate webapp from cloudstack engine, and can even be deployed to distributed machines to load balance user requests.
2. API server will have its own cache DB to store entity information that we want to present to end-user. Note that this cache DB is totally decoupled from CloudStack DB (which is shared by multiple management servers). Each api server can has its own cacheDB. This cache DB can have totally different schema design to represent a correct end-user targeted response view. The cache DB schema will closely map to our new cloudstack resource model plus row-level permission information that can acquired from pluggable ACL component.
3. When API server starts, it will build up the cache DB by fetching fresh data from cloud-engine through REST api, and invoking ACL apis to fill in row-level permission information.
4. API server will subscribe to our event framework to get notified for each resource update to update its cacheDB.
5. During cacheDB buildup, we can also build inverted index using Lucene to support google-like search against it.
6. API server will provide a REST compliant api with the following REST pattern: