6 ms·

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 c

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 https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm [1] https://www.slideshare.net/royfielding/a-little-rest-and-relaxation https://www.slideshare.net/royfielding/a-little-rest-and-rel... [2] https://roy.gbiv.com/untangled/category/web-architecture https://roy.gbiv.com/untangled/category/web-architecture

MaxBarraclough 8y ago
> 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 8y ago
  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 8y ago
    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 8y ago
      > 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 8y ago
bmn__ 8y ago
> 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/9780596529260 • https://oreilly.com/catalog/9780596801694 https://oreilly.com/catalog/9780596801694 • https://restinpractice.com/ https://restinpractice.com/ • http://www.designinghypermediaapis.com/ http://www.designinghypermediaapis.com/
- oblio 8y ago
  Scientists and academic researchers don't benefit from examples? :)
- silverbax88 8y ago
  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 8y ago
    Is this parody?
naasking 8y ago
> 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 8y ago
  > 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 8y ago
    > 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.

MaxBarraclough 8y ago

> 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 8y ago
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 8y ago
  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 8y ago
    > 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 8y ago

bmn__ 8y ago

> 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/9780596529260 • https://oreilly.com/catalog/9780596801694 https://oreilly.com/catalog/9780596801694 • https://restinpractice.com/ https://restinpractice.com/ • http://www.designinghypermediaapis.com/ http://www.designinghypermediaapis.com/

oblio 8y ago
Scientists and academic researchers don't benefit from examples? :)
silverbax88 8y ago
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 8y ago
  Is this parody?

naasking 8y ago

> 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 8y ago
> 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 8y ago
  > 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.