On 6/12/11 12:08 AM, "Mark Nottingham" <m...@mnot.net> 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. _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
