openstack team mailing list archive

[Bryan Taylor <btaylor@xxxxxxxxxxxxx>]

On 6/12/11 12:08 AM, "Mark Nottingham" <mnot@xxxxxxxx> wrote:

>> 
>> 
>> I understand where you're coming from Mark.  I'm still suffering PTSD
>>from the SOAP days.  One of the lessons leaned there was that auto
>>generated language bindings are a bad idea.  Unless you strictly control
>>the client and server implementations -- it all falls apart really
>>quickly.   That's not an XML thing, honestly, I think an auto-generated
>>JSON client would suffer from similar interoperability problems -- there
>>really needs to be a human in the loop.
>> 
>> Given that, we should be building and distributing language bindings
>>for common languages with all our APIs -- it's well worth the investment
>>in my opinion.
>
>+1, especially for the complex ones. It's not a small engineering effort,
>though (especially if some users want synchronous implementations while
>others need async, for example). I suppose that's a real driver for
>keeping the APIs as simple as possible...

This actually has some nice qualities in terms of RESTfulness, because
HATEOAS is a somewhat hard concept and clients that don't get it will
waste their time trying to figure out how to construct URIs to abuse the
RESTful API with RPC style programming. If we write the clients, this
isn't as much of a concern, assuming we get it right :-) . But if we are
struggling to encourage both XML and JSON, uniformly supporting the
language bindings the market wants (java, C#, ruby, python, php for
starters) will be much harder. I'd take a wild guess language binding
writers often prefer XML if they code static languages and JSON for
dynamic ones.

>
>> Also, I really don't see people generating language bindings for REST
>>services the way they did for SOAP.  Note that XML Schema isn't going to
>>give you a language binding in the first place because it describes data
>>types not operations -- and I don't see people using WADL in that way.
>>We use this sort of stuff, internally, for machine processable
>>documentation and validation -- and there are many benefits in both of
>>those cases.
>
>Absolutely; I think those are the sweet spots for WADL. It's also helpful
>in the API design phase, to make sure you've covered all of your bases.

I find that hand written XSDs end up being way more humane than the
generated ones. REST's resource / media type orientation helps XSD sanity
too. SOAP forced a different XSD type for every input and output message,
which would be soul crushing to write by hand. This is what pressured
everybody to auto generate as much as possible when they used SOAP, and
the bloated spew that follows is what caused XSDs to get a bad name. I
think SOAP and WSDL were the real culprits and XSD was collateral damage.
I do agree with Jorge that XSD 1.1's XPath based assertions are a big step
forward. 

As for WADL, its initial cold reception was, in my view, due to
(overblown) fears that the WSDL mindset would infect the REST world. A
server has to describe its entry points sufficiently for a client to know
what it can rely on and whatever artifact solves this is a "contract".
Handwriting it in HTML is fine, but enforcing structure standards is
really hard that way. Unlike WSDL, we can use a mixed approach and
leverage the HTTP uniform interface, standardized media types, and
standard link relations. Atom service documents and OpenSearch description
documents and WADL all do the same thing: they provide hypermedia that's
adept at reducing the number of entry points your server has to advertise.
The difference is that WADL is more generic - it describes resources of
any media type, whereas Atom's service documents are only describing end
points within Atom.

With WADL, once you get to an entry point that is already described by a
well documented media type, your contract is complete and the WADL can
omit its linked sub-resources. For example, I if I show an atom feed's
entry page, I don't need to make a URI template for its pages. So the more
I rely on media types that uses standard link relations, the simpler my
WADL will be. 

Jorge made a mini-schema for Rackspace that includes a type for Atom links
for use within XSD based media types so they can leverage semantic
linking. The rel attribute uses a restriction enumeration. We started with
the IANA link relation registry and this becomes the Rackspace link
relation registry and we could add or remove our own relations if we want.
I've started adding annotation and documentation to some of the relations
to provide richer descriptions than what IANA provides.  Their one-liners
are rather terse for real world work with such a pivotal concept.
Individual services can extend as they please too, and it's clear which is
extension and which is Rackspace standard. Just having it as documentation
is valuable, and JSON representations, by osmosis, benefit from it.