Hacker News Reader

Comment by dwheeler | Hacker News Reader

It's not misappropriated, it's evolved, just as most things are when others try to use them.

Fielding had the notion that the HTTP idea of a few verbs, applied to arbitrary resources, was something to think more broadly about. Others agreed. Over time people decided that for their purposes Fielding's requirement of HATEOAS was unnecessary. I wouldn't say Fielding was wrong, but instead that others had different ideas of what was more important to them.

The key plus of REST is its extreme simplicity if it's reasonable to work within those limitations. Sure, REST has limitations. But let's compare it to SOAP, its competitor at the time. I would much rather use a REST interface than a SOAP interface in practically all cases, and many others decided the same thing.

View on HN

> It's not misappropriated, it's evolved

The article links to Roy Fielding's article explicitly saying it's been misappropriated:

https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

You're free to think the misappropriation is justified, but the word is appropriate here.

> Over time people decided that for their purposes Fielding's requirement of HATEOAS was unnecessary. I wouldn't say Fielding was wrong, but instead that others had different ideas of what was more important to them.

This is fair, but the problem is there is no canonical standard for the vague "RPC-ish API that still mostly uses noun endpoints but not HATEOAS and is a little bit different at every company usually for no good reason" thing that has replaced it.

"1. A REST API should not be dependent on any single communication protocol [...]"

I guess HTTP verbs are right out?

Is REST without hyperlinks for discovery and "state transfer" still REST? People use REST to mean just about any type of API-over-HTTP, which makes the term nearly meaningless. If someone--an individual developer, open source project, or vendor--claims to have implemented a RESTful API, that tells you nothing except that you're going use HTTP to consume it and that it probably uses JSON for data serialization. Why not just say JSON-over-HTTP instead?

You can see attempts to formalize this "HATEOAS-less REST" in frameworks like the Richardson Maturity Model [1].

One less-discussed area where REST has taken hold is in indexing/SEO (i.e. the Semantic Web's success stories). JSON-LD and other RDF microformats/representations are pervasive, while crawlers are much closer to the platonic ideal of a generic client consuming the uniform interface than most web API clients.

[1] https://martinfowler.com/articles/richardsonMaturityModel.ht...

Worth reading "The Hypermedia Maturity Model" afterwards

https://8thlight.com/blog/jason-desrosiers/2018/05/30/the-hy...

I mean, I think you kind of are saying he was wrong? Fielding was pretty clear about some specific principles, and "RESTful" APIs have abandoned all of them.

> I would much rather use a REST interface than a SOAP interface

I've never used an actual REST API, and I wonder if you have either. Considering much of my day job is literally writing integrations for third party APIs, you'd think I'd have stumbled across one at least once if they existed in the wild, right?

In any case, I certainly don't know if I'd rather use one over SOAP; they sound very cumbersome for usage in an API. I do know I'd rather use a simple HTTP + JSON based API of the sort often called "RESTful" than SOAP, but that's quite a different statement!

> Over time people decided that for their purposes Fielding's requirement of HATEOAS was unnecessary.

I'd argue that's wrong. HATEOS is critical to the concept, which describes how websites work. You visit Hacker News. You discover links to resources, articles and their comment pages. You click on the Comment link to navigate to a new resource: the comments page. You discover still further hyperlinks to new resources, like "Reply" to add a comment, discovering a form to submit. The media type of the resource (HTML form) instructs your browser on how to submit a reply comment. At each stage, the change in your user experience is being driven by hyper-media types (HTML pages) and hyperlinks and forms.

That pattern of interaction is "hypermedia as the engine of application state" (HATEOS) and it describes websites. Fielding wrote an article "REST APIs must be hypertext-driven" [1] to further clarify the concept's criteria. The concept of REST applies perfectly to websites like HN, google.com, facebook.com, amazon.com, etc. Compare the behavior of how you interact with those sites with the criteria that Fielding laid out the blog post I linked to [1] and the original thesis. Quoting the blog post:

> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand)

REST describes how the Web works. What's gone wrong is people applying the term to what are HTTP RPC services, which don't have much to do with REST other than that they both use HTTP.

It's a pet peeve, but I wish that people would stop describing their HTTP RPC APIs using the term "REST". Words and concepts and precision matter. I understand what people mean, because this term is misapplied so often, but it disappoints me when fellow computer scientists are sloppy in this way. Modern HTTP RPC APIs are convenient because they can be called easily from the browser by JavaScript, but they don't have anything to do with REST.

Imagine you're a mathematician, and fellow mathematicians start calling derivatives integrals instead; that's basically how badly the term REST is being misused: it's being used to describe systems that are almost the exact opposite of the concept. REST is about describing services that you can interact with with no prior knowledge. REST is about completely decoupling the client and server (in terms of prior knowledge) beyond standardized media types (HTML, CSS, JS). That's essentially the opposite of an HTTP service which has intricate documentation of what URLs exist and what verbs to use on what resources, which the client is expected to know and code into an application in advance. Using REST to describe such a system is living in opposite-land. That's why Fielding clarified that HATEOS is crucial to the concept: hypermedia is what enables clients to interact with a system having no prior knowledge. What system lives at reddit.com? You don't need to have downloaded a binary application in order to use that service; you don't need to know what URLs exist or what verbs to use. You just visit the website root and follow links from there. That's REST.

It is also worth understanding the context in which Fielding's thesis was published, in 2000. Around that time, we had Internet-based systems like AOL that lived on user machines as custom applications, that communicated over the net with proprietary protocols. (AOL provided an experience that's a little bit like a modern browser, but with content just from their walled garden - as I recall.) Fielding's thesis described an abstract architecture that characterizes the modern web, where complex experiences (websites) can be delivered using standard, open technologies (HTML/CSS/JS). It also describes an architecture that facilitates reliability and scaling.

[1] https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...

> Imagine you're a mathematician, and fellow mathematicians start calling derivatives integrals instead

I made attempts in the early days to convey precisely what you write here regarding "REST" to clients and colleagues. My conclusion was that REST spelled "Reasonably Effective Simple Thing" for the substantial majority of workers in IT. So, one minor disagreement regarding your [notion of a] uniform space of "fellow mathematicians".

If we didn't have the debased term of REST, we'd still need to create a new name for the thing that is a connectionless language-agnostic schema-free method call with data orientation that encourages statelessness and some default behaviours which reduce the cost of interop without needing IDL, a thing which isn't CORBA or COM or Java's RMI or SOAP.

Because that thing is what REST means now. I use HATEOAS when I mean the other thing.

I though we could call it UnREST

FIOH from the article is better ŧhough

Beautiful, except for the fact that discoverability is impossible, because clients cannot read the links and think "let's try to click there to see if I can find that data point".

> Fielding's thesis described an abstract architecture that characterizes the modern web, where complex experiences (websites) can be delivered using standard, open technologies (HTML/CSS/JS)

Uh, we already had HTTP for delivering html/js before Fielding’s paper on REST.

Yes but Fieldings paper describes HTTP. It doesn't invent a new technology, it describes and codifies an architecture which already exist.

>REST is about describing services that you can interact with with no prior knowledge

There's a spectrum that I think you are forcing into a dichotomy; I think what you are referring to as HTTP RPC services can also be described as discoverable services, it's just a matter of difficulty, and which spin you want to put on it. At least, the stuff I interact with as "REST", while the discoverability leaves something to be desired, at the same time, I'm not primarily relying on documentation, nor is a binary application involved. What I use daily is hierarchical and while it's incredibly convoluted, there's a fair amount of regularity and I frequently learn about new things via the links.

If I gave you three APIs that all claimed to be REST, could you make more than a few definitive claims on how they're to be consumed? The article calls it out, but let's take something common like what HTTP verb to use when updating a resource.

Once we tackle that, maybe we'll move on to how these APIs model their sub resources.

If we can't make any definitive statements and there's no specification, what does it mean to prefer REST over something else? For me, it means you enjoy arbitrary restrictions on HTTP verbs and their usage and sometimes you can maybe infer how to make a list call on a resource vs. a get call.

> If I gave you three APIs that all claimed to be REST, could you make more than a few definitive claims on how they're to be consumed? The article calls it out, but let's take something common like what HTTP verb to use when updating a resource.

That is a fair request. Btw let's call this RESTful for clarity.

Let me attempt to put it in my own words. I (and I think many others) would expect a RESTful interface to be:

- oriented around a set of resources

- each resource has a unique name, typically a URL.

- Resources can be either collections or individual items

- there is a small fixed set of operations that can be performed on the resources, in particular, get, post, put, delete.

- get returns a collection on a collection resource, and a specific item on a specific item resource.

- post on a collection creates a new resource item within the collection

- put or patch rewrites the item or collection

- delete obviously deletes the item more collection

- the server does not need to record state to order to be able to serve the request, other than perhaps just enough to do authorization and Authentication.

This means that if you give me the name of a resource, I mainly know how to perform common actions upon it. Note that HATEOAS is not listed as a requirement.

I think the real problem is an overloading of terms. What many people mean by a RESTful interface is what I just listed above, which is not what Fielding had in mind with the term REST.

I think the term "misappropriation" is excessively harsh; Fielding does not own a trademark on the term REST. I would agree that clarity is very important, so I think it's better to use another term instead of rest when you mean something not precisely confined to Fielding's definition. I'm happy to use RESTful, but if there's a more common term that's fine.

If you want to specify a RESTful interface, there is OpenAPI, which will give you that information in a formalized way.

I would expect a few simple things - GET doesn't change anything in the server's state (nothing externally perceivable anyway), a 4xx error code means I sent something wrong, a 5xx means the server has a problem, a 2xx is some sort of success.

That's about it really. Everything else is arbitrary. There'll likely be some kind of attempt to structure URIs so that resources follow some sort of scheme, but since most APIs are really RPC instead of information access this is always a nightmare.

Reply on news.ycombinator.com