[occi-wg] Syntax of OCCI API

[Alexis Richardson]

Chris,

I think it would be useful to see some more examples of design pattern
B so that consumers who own use cases can understand your claims
better.  Putting these in an area of the wiki, where they can be
reviewed and edited, makes sense.

Do you think design patterns A and B are in strict conflict?  I.e. do
we need to achieve consensus on A vs B?  And if so then is this an
important early goal in your view?

A couple of other points:

* You cite ElasticHosts and GoGrid as best practice relative to your
assumptions.  In the same context, please can you provide an exegesis
of the SUN API?

* You are a strong and convincing advocate of the view that the core
verbs need not form a large set.  I think the 'size' of the OCCI API
is something on which consensus will take time to achieve.  At this
stage I would like to see a range of strong views, weakly held.  From
my own experience of designing AMQP (with others) a good practice here
is to distinguish a core "MUST implement" set of operations that users
might call frequently, which is then reserved from a possibly larger
set of operations that are administrative, or address optional cases.
Would you be comfortable with that?

And of course - what do other people think?

alexis






On Thu, Apr 16, 2009 at 10:32 AM, Chris Webb
<chris.webb at elastichosts.com> wrote:
> Moving from semantics to syntax, I've been reviewing the draft API design
> which Sam has posted on the wiki at
>
>  http://forge.ogf.org/sf/wiki/do/viewPage/projects.occi-wg/wiki/APIDesign
>
> Sam - congratulations on getting the ball running and something up for us to
> comment on! What follows may sound like criticism, but I agree with the
> majority of your design goals.
>
>
> The beauty of the best existing APIs (e.g. ElasticHosts, GoGrid) is that
> they are very simple to use and to implement. They have a small number of
> nouns and verbs (see my previous mail) and also very straightforward syntax:
> typical commands take only ~100 bytes and could be typed by hand.
>
> I'm concerned that the draft API is heading towards syntax with ~1000s of
> bytes of a relatively complex XML schema - this is a consequence of "Design
> Pattern A" following the Google GData approach.
>
>  http://wiki.cloudcommunity.org/wiki/Open_Cloud_Computing_Interface
>  [I can't find this on the OGF wiki - where is it?]
>  http://www.ogf.org/pipermail/capi-bof/2009-March/000138.html
>
> I'd like to revisit Sam's original email to the CAPI list on design
> goals---I did not see any response from others at the time---and propose
> "Design Pattern B" following the ElasticHosts and GoGrid approach.
>
> I'm happy to expand on this on the wiki. I propose splitting the existing
> API Design page into several parts:
>
>  - Design goals (as Sam's original mail and my comments below)
>  - Nouns and verbs (i.e. semantics of objects; independent of syntax)
>  - Design Pattern A (Sam's syntax in style of Google GData)
>  - Design Pattern B (syntax in style of ElasticHosts/GoGrid)
>
> Do people agree?
>
>
> Revisiting design goals
> =======================
>
>> Design goals
>>
>> * Clarity making it easy to implement and consume (15-20 calls max)
>> * Based on Hypertext Transfer Protocol (HTTP)
>> * Using Representational State Transfer (REST) (with HATEOAS?)
>> * Requires Transport Layer Security (TLS) for integrity and
>>   confidentiality
>> * Relies on HTTP for security (rather than signing requests which caused
>>   problems for Amazon):
>>   o HTTP Basic access authentication
>>   o TLS Client certificate authentication
>>   o OAuth
>
> We agree with all of these. I think the authentication should be via the
> Authorization: header with a set of supported methods announced by
> WWW-Authenticate: in the standard HTTP way. I think it's outside the scope
> of this standard to specify which methods must be supported, although we
> would probably implement plain and cram-md5 as a minimum.
>
>> * Single URL entry point for trivial client configuration and support of
>>   multiple different APIs (e.g. http://api.example.com/occi)
>
> I agree that all API calls should be under a single stem. I would separate
> the ~15 verbs to separate leaf URIs under that stem for simplicity of each
> individual call, as you already do with machine operations, so that the CRUD
> operations also each have their own leaf URIs as opposed to operating on the
> object URI directly. (This is the style of ElasticHosts verbs create, info, set,
> destroy on drives, guests and resources, e.g.
>
>  POST /guests/create
>  POST /drives/create
>  POST /guests/GUEST/destroy
>
> etc.)
>
>> * Single structured data format (e.g. XML vs JSON vs ???)
>
> I disagree here. In the spirit of making the API simple for users with
> different platforms and languages, I recommend multiple skins distinguished
> by HTTP Content-Type. (ElasticHosts today support text and JSON with plans
> for XML; GoGrid support JSON, XML and CSV; Sun support JSON.)
>
>> * XML responses (with XML namespaces for extensibility)
>>   o Atom and/or AtomPub format (for extensive client library support?) ala
>>     Google GData APIs
>
> The key mistake is using complicated data structures: either complex XML
> schemas (c.f. existing draft, which already nests 7 levels of indentation!)
> or simply lists of properties of lists, etc. (c.f. Sun's cloud API).
>
> In both the ElasticHosts and GoGrid APIs, we've been very disciplined in
> making each of our verbs take and return a very simple data structure:
> either a simple list of uuids or key/value pairs of properties for a single
> object.
>
> This makes parsing trivial in any language, and makes it easy for us to
> support receiving and generating the same data with different content types
> (XML, JSON, text, etc. as above).
>
>> * Sensible, transparent versioning - only one API URL for all clients
>>   (perhaps using HTTP content negotiation)
>
> Content negotiation is for agreeing the content-type (i.e. syntax) not
> anything higher level. The content type of (say) JSON is application/json or
> text/json, not something OCCI-specific, so this looks like an abuse of
> mechanism to me. I'm open to suggestions about how this can be done cleanly
> in a way that isn't cumbersome for end-users, though.
>
>> * Random UUIDs (version 4) for internal object identification (opaque is
>>   good for security) e.g. {f47ac10b-58cc-4372-a567-0e02b2c3d479}
>
> I support UUIDs. They can be allocated in a distributed manner without
> locking or worries about collisions, and we use them throughout our API.
>
> However, some providers may want to issue numeric ids, etc., so instead of
> constraining identifiers to UUID syntax, perhaps any standard need only
> specify that object IDs are a unique string from a given alphabet
> ([a-z0-9-]+ say: best to avoid whitespace and syntactically-significant
> characters), which are issued by the provider when the object is created.
>
>> * WebDAV interface for native OS GUI manipulation? (e.g. drag VM from
>>   library folder to cloud to start, delete to stop, etc.)
>>   o WebDAV adds collections et al in a "standard" fashion
>>   o Interesting implications for getting files into and out of the cloud
>
> I think this is something outside the scope of an HTTP API standard, even if
> it's a cute feature for a cloud provider!
>
>> Features
>>
>> * Object persistence optional (e.g. Servers in "stopped" state rather than
>>   ephemeral)
>>   o Allows for "lite" implementations such as those burnt into BIOSes.
>
> This is an issue of semantics rather than syntax, and I tackled it in my
> "nouns and verbs" post. Today APIs vary (ElasticHosts, Amazon have ephemeral
> servers; GoGrid have persistent servers). I lean towards an API supporting
> persistent servers for greater generality than ElasticHosts currently offer.
>
>> Objects
>>
>> * Workload: initially virtual machines (e.g. OVF), potentially later
>>   applications (e.g. Ruby gem, Python egg, Java WAR/EAR)
>>   o Can be identified by Internet media type (e.g. application/ovf+xml)
>> * Container: initially hypervisor (e.g. Hyper-V/KVM/VMware/Xen),
>>   potentially later depending on workload (e.g. Java app server for Java
>>   WAR/EAR)
>
> My concern here is that we do not descend into complicated data structures
> (see above). For example OVF has a significantly complex XML schema in
> itself. If all we need to do is specify simple parameters like megabytes of
> memory or gigabytes of disk space then we do not need OVF to do this.
>
>
> Design pattern B
> ================
>
> In light of these thoughts, I'd propose an alternative "Design Pattern B" in
> the style of the ElasticHosts <url:http://www.elastichosts.com/products/api>
> and GoGrid <url:http://wiki.gogrid.com/wiki/index.php/API> APIs, with one
> URL per verb and much simpler syntax.
>
> Essentially, we would agree a small set of ~3 nouns and ~15 verbs as per my
> other mail. Each verb should take or return a very simple data structure:
> either a simple list of uuids or key/value pairs of properties for a single
> object. This data structure could be expressed in a choice of formats (XML,
> JSON, text, etc.) and would take ~100 bytes or less in any of these.
>
> Shall I go ahead, split out the API design wiki page as I described and
> expand this description of design pattern B?
>
> Best wishes,
>
> Chris.
>
> _______________________________________________
> occi-wg mailing list
> occi-wg at ogf.org
> http://www.ogf.org/mailman/listinfo/occi-wg
>