The APIs for the Sun Cloud: General Discussion: Proposal: Annotating Supported Options on Commands

The APIs for the Sun Cloud was started in February 2009, is owned by russcastronovo, and has 233 members.

» Join This Project

Proposal: Annotating Supported Options on Commands

» Back to forum topics

3 posts

Replies: 2 - Last Post: September 20, 2009 18:05
by: yadieet

« Older Topic » Newer Topic

showing 1 - 3 of 3

Craig McClanahan

Posted: September 16, 2009 13:41 by Craig McClanahan

» Permalink

In the current version of the Sun Cloud API, we specify that requests can contain an open-ended set of name/value pairs in the following circumstances:
* POST to a "controllers" URI on a Cluster
* POST to a "controllers" URI on a VM
* POST to the "attach" or "detach" URI on a VM

It is likely that different implementations of the Sun Cloud API might support different sets of named values for these commands. If the server could indicate what options were recognized, along with other details (description, required flag, regular expression that must be matched), it would facilitate clients that wanted to dynamically present a user interface documenting the available options, and perform prevalidation on the user-entered values before submitting the request to the server.

A reasonable way to accomplish this goal would be:
* Add a new resource called Option that contains name (string), description (string), required (boolean), and regexp (string) fields.
* Add a new resource called Options that contains a hash of Option structures, keyed by the command name they apply to.
* Add an "options" field to the Cluster and VM resources, containing a URI that can be queried (with a GET) to retrieve all the options metadata for that particular Cluster and VM, without substantially increasing the size of the Cluster and VM representations for clients who do not care about this information.

Given these changes, a client presenting a user interface could query for the options metadata whenever desired, and be in a better position to assemble a semantically valid set of options for the particular commands to be executed.

To improve consistency, we should also consider making the "attach" and "detach" commands to a VM back into entries in the "controllers" hash, making the "uri" a required option in the corresponding options metadata.

Comments?

Craig

Tim Bray

Posted: September 18, 2009 19:24 by Tim Bray

» Permalink

I think this one may well have negative ROI. Essentially, this amounts to a miniature schema language provided by the server to constrain the messages that the client sends the server. My experience in this space (which may not be universal) would suggest that:

Schema languages are really hard to design in a way that doesn't tumble into lots of weird corner cases
Requiring clients to understand and implement these adds really significant work; in fact, the lessons of the WS-* debacle suggest that you'd be unlikely to see clients that automatically reconfigure their operations dynamically based on this kind of thing.
This is a tool that could be used by server implementors to create conditions that smell like lock-in; I'd like to require server implementors to accept as wide a range of values as possible. If there's one of the messages/operaitons that's presenting server implementors problems in the face of something clients might reasonably be expected to want to do, perhaps this is a symptom of a mis-designed operation?

In my experience, human-readable specification of behavior is way more useful in practice than this sort of thing. Perhaps, as a useful alternative, each object should have an optional "API-notes" URI field which could be dereferenced to retrieve programmer-oriented documentation as to implementation quirks?

Finally, I agree with the suggestion about "attach" and "detach"

yadieet	Posted: September 20, 2009 18:05 by yadieet » Permalink
	Make it COMPLEX and SIMPLE is our goal.

Replies: 2 - Last Post: September 20, 2009 18:05
by: yadieet

« Older Topic » Newer Topic