openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

On Aug 26, 2010, at 4:31 PM, Erik Carlin wrote:

Jorge, I know you have some ideas about a binding "framework" that could be
used to build bindings in a common manner.  Could you please share your
ideas with the group?


Sure,

We're aiming for consistency with our public APIs so that:

1) Collections are handled consistently
     a)  Pagination works the same across APIs
     b)  Filtering works the same way across APIs
2) URIs are built in the same manner
     a)  Versioning is handled the same way
     b)  URIs follow a consistent pattern
3) Error conditions are handled consistently
     a)  HTTP error codes are mapped in a consistent manner
     b)  Error info is return in the content of the message in the format
4) Special features should be included in every API and handled consistently
    a) Queryable Rate Limits
    b) Changes-since operations
5) Authentication/Authorization...
6) Polling operations and events...
etc...

A big plus of standardizing these sort of things is that it helps simplify life when building language bindings. The idea is to build a  "framework"  that captures, in multiple programming languages (Python, Ruby, .Net, Java, Perl), the things that are going to be consistent between APIs. There are two big plusses to this:

1)  When a new API comes around, we can produce language bindings pretty quickly.  We'll need to add code to handle the new entities, and point to a new base endpoint, but that's about it.
2)  We can spend time to add real value to the language binding, and fixes to a language binding for one API can be shared by others.

Ideally I'd like the language bindings to seem natural and abstract away a lot of the annoying features of the underlying protocol.   For example, consuming a collection should look something like this:

while (list.hasNext()) {
    Server s = list.next();
    println “Found a server: “+s.name;
}

The list handling bits are implemented by the underlying framework.  They abstract away the fact that:

1) The list may be paginated
2) Multiple HTTP requests may be required
3) An authentication token may expire mid-way through the iteration and a new token should be obtained
4) We may be asked to back off for 2 seconds because we've hit a rate limit,
....and so on.

Certainly, we should expose features like pagination for programmers that need them, but for the most part I think a large number of developers would love to interact with our APIs without worrying about protocol level details. The framework provides a way to provide this to clients in all our APIs.

-jOrGe W.