[MaxBarraclough]

> Readers shouldn't have to perform exegesis on your slideshow and blog to get even a vague understanding of what you're trying to get at.

(Ironically?) I've found this same problem to be one of the best reasons to avoid WSDL/SOAP. Too much pie-in-the-sky waffle, not enough pragmatic real-life flavour.

[tannhaeuser]

What's esoteric about WSDL? Arguably, it's verbose and a misuse of markup languages and the WS-* specs might be too generic but WSDL at its core is a straightforward representation of an RPC or REST protocol.

[MaxBarraclough]

From my little time in WSDL/SOAP land: unending boilerplate and busywork, and a constant sense of just get out of my way.

I had to study it for quite some time before I had any idea what any of it was actually for. It was clearly designed with the mindset that it is more important to theoretically support anything imaginable, than to be pragmatic and helpful to today's developers. To put that in buzzword terms, it fails to honour the principles of YAGNI and KISS.

It's very much a product of the ivory tower, and there's a reason it's been almost completely abandoned in favour of JSON/REST.

[tannhaeuser]

> there's a reason it's been almost completely abandoned in favour of JSON/REST

That's kindof ironic to say in a thread about the endless debate about doing REST the proper way isn't it? SOA(P) is really about defining a service in terms of its external interactions in language-neutral descriptions for big applications with long-term maintainability. It's not about developer convenience.

All REST applications I've encountered try to shoehorn state changes into HTTP PUT requests and would have greatly benefitted by expressing these as explicit state transitions in a WSDL-like RPC model. None has made the slightest attempt to represent state via HATEOS and advertise interactions via hyperlinks, which is the entire point of REST and loose coupling. In typical server-side languages other than JS/node.js, JSON isn't a native object serialization format and must be produced/consumed exactly like XML (eg. by using binding annotations or similar). So I'm not sure what has been gained, other than a mess of JSON-over-http services without transaction boundaries for the next generation to clean up.

[barrkel]

JSON is significantly superior to XML for one simple reason: edge-labeled graphs are isomorphic with common programming language data structures and node-labeled trees are not.

I've not used binding annotations when working with server-side JSON in Ruby or Python, and there's little need to do it in Java unless you want a mechanized description of your API data structures to do other things with, like documentation or tool-driven schema validation.

HATEOS is nuts for an API layer. It forces an overly chatty API because you need to navigate a graph to perform actions, rather than looking up paths in docs - but the paths don't go away, they just move from being path templates to resources to being path of navigation through a series of responses. The essential complexity is constant, and the need for hard-coding endpoint knowledge into the API client hasn't gone away, it just moved.

HATEOS makes some sense for user interaction, but even then it works poorly for people who fork their navigation: open up several child pages for a list of items, add each to the basket, then go to the checkout. Do they all go in the same basket, or do you have several different baskets depending on the path of navigation? HATEOS will guide you to the latter, because hypertext drives the state, rather than some hidden state. HATEOS works much better in a read-only context, where you're e.g. sorting and filtering through a list. Actions, less so.

[tannhaeuser]

Your points are appreciated. I think your graph-theoretical interpretation of the XML-vs-JSON debate, though, is missing the point that SGML/XML describes an information serialization using a grammar formalism (regular tree languages), as opposed to JSON which is essentially described by co-inductive type theorems. Though JSON is lacking because it can only represent trees rather than more general graphs, and because of JavaScript's very weak type system (eg. wrt. primitive types as well as it's lack of a natural type system for JSON compound types, hence requiring kludges such as JSON schema).