[mratzloff]

The main problem with REST is Roy Fielding's communication style.

Here's a quote from a 2008 blog post:

Apparently, I use words with too many syllables when comparing design trade-offs for network-based applications. I use too many general concepts, like hypertext, to describe REST instead of sticking to a concrete example, like HTML. I am supposed to tell them what they need to do, not how to think of the problem space. A few people even complained that my dissertation is too hard to read. Imagine that!

Yeah, Roy. It's called being an effective communicator. Effective communicators include stories and concrete examples to help bring the audience along with them, instead of lengthy discussions of abstract concepts. 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.

To be clear, any difficulty with REST in practice is a direct result of an underspecified concept without a clearly defined RFC as it relates to HTTP. Fielding didn't define anything about REST in terms of HTTP. All of REST, as it relates to HTTP, has been an application of what other people think he meant.

Nowhere in Fielding's 2002 academic paper[0], his 2008 talk at ApacheCon[1], or his blog[2] does Fielding have clear examples or thoughts on the kinds of specific details that Web developers often struggle with.

Fielding, in my estimation, seems principally concerned with three things with regard to REST:

1) Every important resource has its own URI.

2) All interactions against that URI should be stateless and cacheable: all application state that is specific to the user should live on the client (e.g., local storage for browsers), and all shared state should live on the server.

3) Interaction with that URI should be the same regardless of client (browser, mobile app, etc.).

Everything else is left as an exercise for the reader.

[0] https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

[1] https://www.slideshare.net/royfielding/a-little-rest-and-rel...

[2] https://roy.gbiv.com/untangled/category/web-architecture

[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).

[bmn__]

> It's called being an effective communicator. […] bring the audience along […] Readers shouldn't have to perform exegesis

He's optimising for communicating with his peers: scientists and academic researchers.

If you find this communication hard to digest, then chances are you are not part of the intended audience. It is then mostly pointless to complain or try to change his wording.

You can buy books from other people who deliberately target developers.

• https://oreilly.com/catalog/9780596529260 • https://oreilly.com/catalog/9780596801694 • https://restinpractice.com/ • http://www.designinghypermediaapis.com/

[silverbax88]

That's because they have generations of narrative dialog that is only intended to be used in academia. They use superfluous and oftentimes nonsensical language because they are attempting to create an environment of pseudo intellect, where none exists.

[jjaredsimpson]

Is this parody?

[oblio]

Scientists and academic researchers don't benefit from examples? :)

[naasking]

> Yeah, Roy. It's called being an effective communicator.

An author uses technical jargon and concepts familiar to his intended audience. Fielding's intended audience for his thesis is other people with PhDs. His writing was perfectly cogent if you have this level of knowledge.

The people who really failed REST are the blog authors who didn't have the necessary background to evaluate the REST constraints and started talking about REST despite not understanding half of the thesis. This is what diluted the term.

> Fielding, in my estimation, seems principally concerned with three things with regard to REST

You missed the central importance of hypermedia.

> Everything else is left as an exercise for the reader.

That's like saying an RPC library leaves designing and building your specific API up to the reader. Of course it does, it has no business imposing any more constraints than are needed to fulfill its purpose.

REST specifies some architectural constraints that entail certain distribution and scaling properties, that's its purpose. Anything beyond that is domain-specific logic.

[ken]

> An author uses technical jargon and concepts familiar to his intended audience. Fielding's intended audience for his thesis is other people with PhDs.

Perhaps, yet his blog is written in exactly the same style.

Who are all these ComSci researchers who are most comfortable with these concepts and distinctions, anyway, and who are also designing web APIs? At some point, if you wish any real system to use your ideas, you need to communicate it in some way that explains it for a typical software developer. If you write a blog in the style of a thesis, only thesis committee members will ever want to read it, or be able to understand it.

It's like the old story of the plumber who discovered hydrochloric acid clears clogs, and when he reported it, some scientists told him "The efficacy of hydrochloric acid is indisputable, but the corrosive residue is incompatible with metallic permanence", and he thanked them. Repeat several more exchanges, with even more jargon. Finally, they tell him "Don't use hydrochloric acid. It eats hell out of the pipes."

[naasking]

> Who are all these ComSci researchers who are most comfortable with these concepts and distinctions, anyway, and who are also designing web APIs?

More than you realize, I'm sure. There are plenty of industry people who can understand theses and other research publications. You can find them here, on reddit, on stackoverflow, and on lambda-the-ultimate.

> At some point, if you wish any real system to use your ideas, you need to communicate it in some way that explains it for a typical software developer.

That's what books and blogs are supposed to be for, but how many of these people do you think spoke with Fielding before writing about REST to ensure they got it right?

Fielding's emphasis on abstract concepts are because REST isn't tied to HTTP, or HTML, or XML, or JSON. He's trying to explain calculus to you so you can solve many problems, and you keep focusing only on how to calculate velocity given acceleration just because that's the problem in front of you right now.