Could I get some feedback on the following strategy for mapping CloudStack RPC
commands to HTTP requests?
The general approach is to:
1. map each category of command to a URL. Each category corresponds roughly to
a resource type being manipulated.
E.g. /cloudstack/latest/storagepool/
2. make the command itself a path under the category
E.g. /cloudstack/latest/storagepool/create
3. make resource changes using a POST request with parameters JSON encoded in
the body
E.g.
POST /cloudstack/latest/storagepool/{create | modify | destroy}
POST /cloudstack/latest/volumes/{create | destroy}
POST /cloudstack/latest/vm/{start | stop}
4. query resource state using a GET request that identifies specific resources
with a query parameter
E.g. GET /cloudstack/latest/vm?id=1&id=2&id=3
Commands are mapped to paths for simplicity. Identifying CRUD operations such
as create, modify and destroy from the path limits the HTTP methods to POST and
GET.
Serialising parameters as JSON in the body of a POST request is for simplicity.
Passing all command data in the URI is difficult, because URIs are ill suited
to expressing object trees that exist in complex commands such as the VM
StartCommand. Since parameters such as VM identifier are already in the body,
static URIs can be used for many commands.
Commands that push data from the agent to the server have to be implemented as
polling operations. This applies to initial configuration commands and the
hypervisor ping. Agent configuration will come from HTTP POST versions of
StartupRoutingCommand and StartupStorageCommand, rather than a config file
copied to the hypervisor as was done with KVM. To simulate a PingCommand the
ServerComponent will use a HTTP GET.
Versioning is by way of dated path rather than version number. Assuming the
latest API is completed 2013/02/04,
/cloudstack/latest
and
/cloudstack/2013-04-02
refer to the same API.
