Donal, This looks very good. I especially like the fact that we didn't go do a bunch of mapping of json to url paths. After all, we're don't need full REST for agents.
+1 --Alex > -----Original Message----- > From: Donal Lafferty [mailto:donal.laffe...@citrix.com] > Sent: Tuesday, April 2, 2013 12:00 PM > To: cloudstack-...@incubator.apache.org > Subject: [DISCUSS] RESTful API for CloudStack agents > > 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.
