Roy Fielding's Misappropriated REST Dissertation
twobithistory.org
twobithistory.org
As someone who both wrote a (client-side) web browser in the 1990s and at the time also built server side HTTP systems, the piece gets it almost entirely wrong, and the degree of misguidedness in the HN comments is almost worse.
But I guess that is how things go. Sigh.
The competitor to ReST (representational state transfer) was not SOAP. It was and is RPC, and by extension, object oriented languages.
The brilliant recognition Roy had, the genius of ReST, is that most systems are about data, not behavior, and solving for distributed system reliability was mostly about moving data around, statelessly.
At the time, distributed systems were not the thing they are today, but what people were doing was informally called distributed objects- things that have state and behavior, the lifecycles of which are manageable remotely. Incredibly complicated stuff, failed all the time. You can see a good example of this in Java RMI, which was still shipping in Java until recently. The term "agent" has been deeply overloaded but it was also applied here.
I think there is a good argument there is a direct line between Roy's insights, as expressed in ReST, and functional programming and the immutability revolution, and also the CAP theorem. The system design principles are exactly the same.
Hope that story gets a proper telling some day.
https://en.m.wikipedia.org/wiki/Common_Gateway_Interface
The web was invented so that supporting documents in research can be addressed via hyperlink, as opposed to just by citation, for more fluid understand of research material and technical documents. The hyperlink address of those supporting documents indicated where in the system those documents reside and that form of addressing was the basis of the URL. In later practice the URL would denote a service own via domain and a path on that server where documents reside.
https://en.m.wikipedia.org/wiki/Uniform_Resource_Identifier
As the idea for web standards began to emerge in the mid 90s there came the idea of the URI. URI does not represent a location, as in a URL, but instead a unique identity. The idea of URI became a parent taxonomy to existing things like URL, URN, ISBN, and so forth. The idea for URI was influenced by the idea of email addressing which was at the time already in wide use as both a unique identifier and an address location. An example of this idea worked directly into a technology is RDF.
https://en.m.wikipedia.org/wiki/Resource_Description_Framewo...
Fielding was deeply involved in the work of addressing as he was co-authoring several of the related RFCs that would in several years get rolled up in RFC 3986, 5 years after the dissertation.
The most influential idea introduced by REST is that as an architectural style an address can serve as an idea scheme instead of just document location on a distant server. Nobody cares where on a server a document resides so long as the address returns the intended content. Bigger still is that an address does not have to resolve or return anything to provide a variety of functional uses.
And yes URL/URI became substantially Roy's work, an idealized digital reference syntax, as was also the fact that what you got at a particular address- if you were to get anything- was data- maybe structured as a media type. There was no commitment to behavior or semantics. Just data.
What I never got a complete sense of, from reading the docs and mailing list convos at the time, is how much Roy came to HTTP with the data-driven perspective, vs how much he absorbed from what were initially TBL decisions- organized around sharing documents and data- and from the presence of Gopher and FTP- dominant protocols at the time and both entirely data driven. And of course going back further- Ted Nelson, Vannevar Bush and others- their relevant work was almost entirely in the data driven vein.
The conversation should be about what patterns help us build useful API's, not about canonical or heretical REST.
Side note, you probably know but OWL and RDF and related semantic data and graph model standards are "machine-to-machine" usable and have a clear lineage to Roy's work. HATEOAS was a stab in that direction, but insufficient.
Agreed. Java EJBs,specifically distributed session beans, were the incumbent, along with DCOM objects on the Windows side.
Also, in my experience, I don’t ever recall anyone using RMI directly. EJBs were used much more frequently than direct RMI. However, IIRC distributed session beans used RMI under the hood.
We also did plain XML over HTTP using Internet Explorer’s XMLHTTPRequest object in JavaScript. Not SOAP, just custom xml. But that was client side...
We already have plenty of protocols for that, REST isn't one.
I know (at least superficially) what these things are, but I don't quite see the connection. Do you mind explaining please? It certainly sounds like a very interesting subject for a blog post or two.
Roy (and others) rewrote/enhanced early TBL HTTP specs, and then Roy wrote the thesis describing the thinking behind the new spec, defining an "architectural style" called ReST (Representational State Transfer). So the thesis is in effect a defense of work already done, and an expansion and consolidation of thinking behind the motivation.
The short version is that ReST is about the primacy of data, and of not making application level semantics into a network protocol. All you can do with HTTP are abstract CRUD operations- the fact that those operations may entail complicated application-level behavior behind the server to update a data model or send an email or generate an image or whatever- are irrelevant. (RPC/gRPC is an anti-pattern / counter argument to this.)
Functional programming is also about the primacy of data. Data, rather than objects, matter. Work in terms of generic functions explicitly applied to immutable data, creating new data, rather than application-and context-specific mutations implicitly applied to objects, subtly transforming the state of the object, serving the interest of encapsulation, but in practice obscuring and confusing. HTTP's URIs- references to data- small number of "methods", emphasis on content and media types- versionable data structures, not classes- and the distinction between idempotent and non-idempotent write operations- a distinction almost never made in the interfaces of objects- comes from the same motivation as that which leads to functional programming.
This is a little hard to see now but distributed objects- encapsulated state and behavior- were a huge thing in the early days of the Internet. Objects don't scale. Distinct functions and data do. ReST and HTTP enshrine this.
Finally, the CAP "theorem" points out that distributed systems have to choose between consistency and availability in the face of network partitions. Note that CAP had not been coined when Roy did his thesis work. He nevertheless incorporated into ReST- with HTTP cache semantics- the key implications of CAP. HTTP cache headers and HTTP response codes allow for both consistency and availability to be tightly defined. HTTP cache is taken for granted now with URIs and browser caches and CDNs and cache-busting and so forth, but in retrospect should be considered revolutionary. A strong version of this statement is that CAP is a mere footnote to ReST.
Hope that helps. Cheers.
The irony is that this 'REST' is used now in part to support lifecycle management of live objects, in the browser, but this has architectural implications.
Further, dogged adherence to arbitrary 'REST' or FIOH explains the growing popularity of a growing number of non Restful http protocol extensions like websockets, webrtc, graphql, as people search for rpc alternatives for things REST was never intended for. This seems to be a pretty valid criticism of the state of industry 'REST'.
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.
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.
I guess HTTP verbs are right out?
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...
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!
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...
Because that thing is what REST means now. I use HATEOAS when I mean the other thing.
FIOH from the article is better ŧhough
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".
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.
Uh, we already had HTTP for delivering html/js before Fielding’s paper on REST.
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.
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.
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.
The custom media types are the key to this. Hypermedia API is like browsing a HTML website, but instead of HTML you use a custom markup language that drives your application's native views (or you can interpret it as sending commands to perform or options what the app can do next).
So it's not a method of discovery how to use a networked database or invoke remote function calls, but a server-driven UI. That makes it extensible without client-side changes, because you can link more endpoints the same way you can add more pages to a website.
That rarely happens in practice. The vast majority of developers put HTML, XML and JSON+(link extensions) to use as hypertext/hypermedia substrate. These are not custom languages, but applications of standard languages.
And let's be frank, very few businesses are actually really doing representational state transfert.
Most are just taking advantage of HTTP stateless properties with a coat of RPC on top.
SOAP was heavy and complex but at least it had a spec, so no endless debate as to what "proper SOAP" was. It was up to libraries to either follow the spec or not, many did not.
This is also why GraphQL adoption was so fast. Developers don't care about ideas if there is no spec to implement or reference implementation, most aren't academicians.
edit: again, my comment is obviously referring to API, AKA 2 web apps communicating with each others, not an internet user clicking on links with an web browser.
Every website on the Internet is doing representational state transfer. REST describes the interaction of humans using browsers to visit websites. It's not (mostly) meant to describe APIs for use by machines.
When you understand that it describes websites, then it's also not a hard concept to understand. Example REST services are: reddit.com, google.com, facebook.com, amazon.com, ebay.com, etc. Compare how you interact with these REST services with the criteria Fielding clarified in his blog post "REST APIs must be hypertext-driven":
https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
When you build a website you typically meet these criteria without effort. It's a natural part of the experience. Machines can also interact with REST services, though usually not in the same way as people. (I agree that REST has minimal relevance to design of APIs that are intended for use by other software)
We're talking API here, obviously, AKA 2 web apps communicating with each other, through basic HTTP clients. A browser is anything but a basic HTTP client. There is no user clicking on links in a contextual fashion here. So the point you are trying to argue doesn't even matter.
Your comment is ironically the very reason why REST as an idea is irrelevant to API developers and why trying to force a REST paradigm onto API is a bad idea. Very little HTTP clients used by API are sophisticated and intelligent enough to behave like an internet user browsing hyperlinks.
But they easily could be and should be. Obviously if only HTML is getting transferred, that's a difficult representation for a machine-based API to reason about. But XML or JSON is easy to teach a client to reason about.
This is kinda the whole point of the Semantic Web and just about everybody missed it. So now everybody is finally actually doing Semantic Web [ish] stuff; they just call it GraphQL.
Yes, almost no one needs 100% REST, browsers do basically.
GraphQL adoption is not particularly fast IMHO, and being the official Facebook API probably helped :)
Regarding your edit: REST is the generalization of users clicking links. That's why almost no one uses and needs full REST, because that kind of flexibility and future proofing is excessive in almost all business settings.
It's worth noting that those are not extracted from Roy's REST, because they were never in it.
It's like the word "literally" being used to mean "not-literally".
Roy's design was about using custom media types, over any protocol, discoverable via hypermedia. Popular design today is to use just application/json, over HTTP, with externally defined URL schemes. There's nothing wrong with that design — use whatever fits you. Perhaps its even fair to say that Roy's design has failed to gain traction (apart from describing HTML with forms), but what Roy described as "REST" is not what is now commonly understood as "REST".
It's a digression, but I don't believe this is actually a thing.
Certainly, "Literally" is often used in figurative statements. That's different from using it to mean "figuratively".
I think it's a hyperbolic use of the original sense of "literally"; "literally X" often means "so very like X it was almost as if it was literally X but of course you know the use remains figurative".
In much the same way, if someone says "you left me waiting for days" we don't say "days occasionally means minutes"; we say that people exaggerate. I have never seen an example of a statement that would have been understood literally but for the addition of "literally".
I think Websters got this wrong.
Note that I'm not saying that "literally" is marking hyperbole, but that it is itself being used hyperbolicaly.
All of these are "correct" not because they are separate, established meanings of "literally" but because they are perfectly natural things to do with a word. I would think that this is also why, in an analysis that mistakes this for "divergence", that divergence was pretty much immediate.
It's a distraction, so I no longer call it REST. Words change and discussions about what the word REST should mean is far less interesting than solving API design problems.
I think it’s useful to read and understand the concepts in Fielding’s dissertation. But don’t set out to build a RESTful API. Set out to build the most appropriate API for the problem you are solving, which may or may not involve incorporating various elements from Fielding’s dissertation.
No, "REST" has devolved. REST from the original dissertation is more flexible than any "REST level-X" APIs you'll see in the wild.
No, it wasn't. The original idea of objects in languages like Simula was what you would later find in C++ and Java: A "this" pointer and a vtable, essentially.
Only later did languages like Smalltalk take the "dynamic" part to the extreme, with their "everything is an object" and "procedure calls are messages" philosophy. Those ideas were not adopted broadly, because they aren't good in general, they have severe trade-offs.
Some of them I find quite interesting, not usually discussed, such as dataless programming, where you program against an abstraction. This is very widely considered a good style in OO today. Go and Rust specifically with their interfaces and traits. Another, more subtle one would be Clojure, which seems to be paradox because it is a data driven language on the surface.
Message passing was also more widely adopted in different forms that are not considered/named OO but carry similar semantics.
The everything is an object idea can be found at least to a high degree in dynamic languages like Ruby, Lua and JS.
I think we're starting to come full circle there, with static type annotations and JITs optimizing with "hidden classes".
The author mentions SOAP as what REST came out of, but there were really at least two camps - the formal SOAP camp and Wild West of doing it however you want with POST calls. People were frustrated at these extremes. Regardless of the intention, Fielding's dissertation came at the right time and showed us a path that was simpler than SOAP, but more formal than the Wild West method.
I've been arguing for a while that we should stop pretending. I'm glad I'm not the only one.
You seem to forget the litany of articles claiming everybody did REST wrong all the time… Yes, it doesn't matter today. We have GraphQL that put an end to that era of complete bullshit.
He wasn't suggesting people build APIs; he was suggesting people build websites.
PUT, DELETE, and.. kinda... HEAD never got any use until REST APIs.
So if the true representation of representational state is a simple website like this, then large parts of that "spec" were irrelevant to 99.9% of sites before "web services".
He wasn't writing about how to build web APIs. He makes no mention of HTTP verbs, and nothing about REST requires such verbs to even exist in the underlying protocol. He was discussing, at a high level, how you might design a protocol like HTTP/1.1, not how to build an API on HTTP/1.1.
Further, the single key feature of a REST API is hypermedia, aka, links. If you do want to use HTTP for your REST API, GET and maybe POST are 100% of what you need, because that's what you use to follow hyperlinks.
To quote Fielding:
> A REST API should be entered with no prior knowledge beyond the initial URI... From that point on, all application state transitions must be driven by client selection of server-provided choice...
Not mentioned: What HTTP verb you need to use to trigger the state transition, because it doesn't matter. And in fact, to the extent that a client has to "know" which verb to use, that actually goes against REST principles.
> So if the true representation of representational state is a simple website like this, then large parts of that "spec" were irrelevant to 99.9% of sites before "web services".
Again, there's no spec, unless you mean HTTP/1.1. And to the extent that we're talking about the principles that underpin the entire HTTP protocol, arguably they're relevant to 100% of sites. :)
Show me a REST API! Better, take a popular API and show me how it would be as REST.
http://oreilly.com/catalog/9780596805838 chapter 2
http://oreilly.com/catalog/0636920028468 chapter 5
So please link to the REST specification if it exists or the reference implementation of REST.
Edit: I just read your other comments. You just want to have an argument. Bad user, no cookie!
Because your bunch of links has nothing to do with the matter at hand. Everybody has an opinion about what REST should be, nobody can come up with an implementation of what a perfect REST API ACTUALLY is.
And spare me the ad hominem. That's a cop-out and childish.
https://petstore.swagger.io/ is an example.
Quite a few companies use a similar format to document their public APIs.
Why can't we just call this an "HTTP API"?
Where is the single entry endpoint or the response links driving application state?
The consensus seems that REST is SOAP but with JSON instead of XML and uses HTTP methods to... I guess to keep everybody annoyed.
*except arguably compilers. Its very rare that people look at the asm output outside of specialized domains.
Pass text messages, which are text so you can interpret what is being sent and received much more easily than a binary protocol, using only binary tools.
The REST approach is essentially: "Everything is a noun, and you have 4 verbs"
Building a good API with everything as a noun and only 4 verbs is quite awkward in my opinion.
Lots of API calls might need to pull data from multiple different "things" (nouns) to generate the reply, and in REST you're urged to require multiple calls to accomplish that. Awkward and slow.
Four verbs are enough if your intention is to implement REST. If what you are implementing is RPC I can understand why you get annoyed. REST was never intended as basis of ALL communication, but the IT world seems sometimes bent to exploit an idea well beyond its limits.
However, a vast number of web developers (dare I say "most") became convinced the proper way to "think" about their architecture was "as if it were all nouns" (even when it obviously wasn't), because they thought they were having an "epiphany" about how to use REST
...when what they were really doing was conforming to software development "meme" (or trend)
I don't think "developers thinking their architecture was 'as if it were all nouns'" is somehow limited to REST or even web APIs. It's a fundamental part of objected oriented design philosophy.
http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...
Here's my own code that is such an API:
https://github.com/Clay-Ferguson/quantizr/blob/master/src/ma...
You can point out that 80% of those API methods are resulting in some kind of CRUD method, and I'd agree, but nonetheless trying to make it a true REST API would be super awkward and verbose, imo, because lots of those functions result in multiple CRUD ops on multiple different types of data.
When I design an API, I think: "What is this operation called? What data is best to send upstream, and what do I want to get back." Then I design the API. The API is a wrapper around an abstraction layer of functionality. REST is all about removing that abstraction layer which is moronic.
In my experience, the nice part about designing APIs in a REST-like manner is that they encourage you to think in terms of observable operations. For example, instead of "calling" a long running blocking method, you create a resource that represents the long running operation, and now you can check its status while it is running, report progress, cancel it.
Basically, when designing a REST API you think about the exact same things you are saying - what is the operation called? what data does it need, and what does it return? - and then you represent this as a resource that can be created with the right input, and that will point to a result resource for the final output.
For example, my usual pattern for things outside of CRUD is something like this:
--> POST .../operations/renderNode {ExecuteNodeRequest goes here}
<-- 202 Accepted Location: .../operations/renderNode/891
--> GET .../operations/renderNode/891
<-- 200 OK {status: IN_PROGRESS, percentage: 78, ... (includes initial ExecuteNodeRequest params)}
--> GET .../operations/renderNode/891
<-- 200 OK {status: SUCCESSFUL, percentage: 100, resultURL: .../operations/renderNode/891/result, ...}
And then on GET .../operations/renderNode/891/result, you have the final result.
Of course, if the operation finishes quickly enough, any of the polling steps can be omitted - e.g. it can directly return 200 OK and the result URL for the initial request. If you have WebSockets support, you can also be notified via WebSockets when execution finishes, instead of polling.
It may look like more ceremony, but in general, for long running operations that will be called from a browser, this kind of approach is a requirement anyway, since the number of connections with a particular origin is extremely limited.
Note that I also think your API would be much more concise as a REST API, since all of the miriad "setX", "getX", "createY" methods would be reduced to a few resources with multiple fields, that you can simply GET to see all fields, or PATCH to change a single field (or even change multiple fields in a single request).
Where REST makes that awkward is that many "verbs" I want to use in my API result in multiple such objects being created on a server, and multiple objects being returned (in some wrapper class), and that's awkward with REST because REST is all about making those nouns directly accessible. I don't want that. I want a vocabulary of actions. My client "does things". Doing is a verb. Verbs operate on nouns. The nouns will all exist but they themselves aren't the API.
My other gripe is that I don't want the tech stack dictating to me ahead of time what my verbs are. Some of my verbs might do a create, and update, and some deletes, all in one verb as part of a transaction. There's no such thing as "Is this a create or an update or a delete API call?" It might be all those simultaneously.
Each API call should have a unique Request object and and Response object. When your request/response are specific verbs, you can then later rename the verbs and easily add additional info to the Request and/or the Response without redesigning all your objects. Objects should be designed to model the data itself and NOT have any direct relationship to the API. Objects are in the language of the API verbs, but they don't control it.
For example, SQL has simple verbs because it doesn't want to know what are the actual operations executed by the application (for example, verifying status of an existing process, checking optimisting lock, etc.)
Another example are some remote memory interfaces which basically transfer blocks of memory back and forth without knowing what is the operation for. You build your higher level, business logic-aware protocol on top of it.
The same way, REST is about intentionally not getting involved with the imperative style and instead provide transport protocol that will make it possible to refer to the things as resources, discover resource graph through hyperlinks, etc.
The business logic is supposed to introduce changes to the object but use REST to only transfer representation of the changed state (Representational State Transfer) without burdening it with RPC details.
That is why so many APIs fail to use REST effectively, because designers do not understand the goal and limitations of REST. It is conscious decision not only what the API does but also what it is not supposed to do.
To update the user the REST-ful way would be to allow the client to fetch the user document, introduce changes client side with whatever logic the client wants and then transfer the representation of modified state back to the server with a simple verb (same way we interact with filesystem through reads and writes without kernel ever knowing what this is). The server decides what to do with these changes.
Trying to burden the kernel with information about what the operation is is futile but that's what usually happens when people design "REST"-ful APIs.
I'd politely disagree with that. I think most REST fanatics ACTUALLY DO claim that their beautiful arrangement of nouns and their 4 CRUD verbs are capable of replacing RPC, because they've become convinced the "procedure" part of RPC, means that RPC is inherently built around functional programming which is verbs, and they think they've found a better way than using a custom vocabulary of verbs.
So they're using REST instead of RPC, because "verbs are bad".
I'll just restate my opinion that the concepts of "functional programming" are not somehow rendered obsolete whenever the machine you're talking to happens to be remote. Sure, there are certain challenges involved with designing a 'remote' API that can arise involving latency and bandwidth considerations, but those limitations in no way imply a solution where you throw out your entire set of "verbs", like REST does.
Of course, you then build up functionality over those base verbs, just like in a program. But your programming language doesn't have a verb for each function you might want to write. It just has the base 'call' verb.
As for me, for 30 years I've known software function calls are inherently verbs and I'm not gonna let a trending "meme" (like REST) convince me otherwise. haha.
I mean it's not so much the "nouning" of verbs that's the problem, but it's the loss of the ability to use verbs that I find so appalling.
I mean if I need to run some reports it had better be called "runReports()" not some janky update of a state of some 'report' object to change it to 'running' state. So silly. REST is so jank.
I mean what if "runReports()" needs to start N number of independent reports and return the status of startup of each one. With REST you always end up fighting things like that which are totally trivially easy without the REST nonsense.
It feels like jumping through hoops but you end up with a more solid API for the web.
``` let user = api.getUser(); user.setName("Clay"); api.saveUser(user); ```
That's just a basic RPC API. No one will ever convince me that turning all that into some kind of noun-based equivalent is better.
The fact that a GET and a POST are HTTP verbs that match up to that is is meaningless to me because I could care less about the HTTP layer in my API design. APIs should be decoupled from all underlying architecture as much as possible. REST is about TIGHTLY COUPLING THEM as much as possible. Bad idea.
Well for anyone else listening, a RESTful design would help you know whether you're creating or updating a user. You would know if you're allowed to repeat the request without side effects. That's useful in a distributed api where half open requests are inevitable.
However with REST I can't "transmogrify" a user. Do you know what a "transmogrification" is? No you don't. Because REST doesn't do that. It's a domain specific verb I made up.
To force REST to work you'd have to invent a new noun called "transmogrify state", even if no one would have ever conceived of that state in a functional programming design. Whenever you end up inventing new objects specifically to work around architectural limitations, that's not a simplification. :)
Functional Programming works. Nothing invalidates verbs just because you're doing them over HTTP, for example. Your API design should have no clue if it's running over HTTP or something else.
If your API had a /transmogrification/<id> resource. I would know how to query its state and possibly edit it. I have a clear place to look for previous transmogrifications without crating a new one and I even have a nice query syntax support.
Or maybe you don't support GET and return a 405 response. That's ok too.
* Limits number of verbs to CRUD ones (HTTP).
* Makes every verb into a noun.
* Tightly couples HTTP-codes into your API.
* Requires creation of many endpoints you don't really need.
* Makes it awkward to have a single request that updates multiple different types of objects, or queries different types of data.
yeah, I don't want any of the above in my life.
REST is a protocol-neutral architectural pattern, so, yes, you should care less about the specific protocol and it's verbs. REST is about resource representation (the nouns and the ways they are represented as data) driving everything, not wire protocol verbs. HTTP is itself a REST API built on top of TCP/IP, but other REST APIs don't have to be built on top of HTTP, or even tied to a single underlying protocol.
> APIs should be decoupled from all underlying architecture as much as possible. REST is about TIGHTLY COUPLING THEM as much as possible.
No, it's not, even approximately.
REST over HTTP uses standard HTTP methods with their HTTP-defined semantics rather than unnecessary ad hoc, API-specific extensions because, well, first, why would you do anything else if you want to use a standardized underlying protocol? And second because: “A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, [...]” https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
I do an HTTP "post" to send up a JSON object as a request, and I get a JSON object back as the reply. No one is going to tell me there's a "simpler" way. There isn't.
For example, if I need to delete data, I'll call "deleteSomething" as an endpoint. I could care less if HTTP has a delete in it's language, because I don't want/need any of that coupled into my API or affecting my API in any way whatsoever.
That way my API can be moved to some non-HTTP pipe at some point and it will remain unchanged. It's just like how in good OOP you ideally code to 'interfaces' rather than coding to 'objects' directly.
Here's an example controller: https://github.com/Clay-Ferguson/quantizr/blob/master/src/ma...
You can tell it's perfectly type-safe on both client (TypeScript) and server (Java), and the API itself doesn't have any clue it's even be running over HTTP, and that's a good thing.
What you seem to be stating is that there's more to that on the web and that HTTP has a reason to exist. I agree. It makes sense for the language of the browser itself to be basic CRUD-type calls to servers (which is what HTTP is)
But for a specific RPC interface for a specific WebApp client, trying to meld THAT API into HTTP (the goal of REST) is awkward as all hell and that IS what everyone's using it for.
user = UserApi.get(id)
user.name = "Clay"
UserApi.put(user)
Does using put instead of save really bother you that much?
The tight coupling doesn't matter if you are building a web service. HTTP is how they work.
I fail to see how that's janky, it sounds like a great abstraction. I would have a 'createReports()' method that returns an array of Report objects that all correspond to a record in a database. Easy to query for the state, id, or any other details I might need. Doesn't get any cleaner than that in my opinion.
My point is that the entire endpoint would be mostly verbs (like runReports) and use only the HTTP POST to communicate. So I'm "ignoring" the fact that it's running over HTTP, I would ignore every "rule" of REST, because REST offers nothing but hurdles to jump over.
One thing that kind of gets you is that HTTP itself is not the best transport for all of these things. If we are talking about something that has to run over HTTP, we might do something like create a run of reports (maybe a POST to reports/run). That could return a list of report_ids that were created and their associated status, with an run_id associated with the collect run. There's no fighting!
However, if you want that data streaming back to you, this is where you might think you want something more like WebSockets. For some use cases, this can be more efficient than having the client polling to see if the result of a long running process is ready. It all depends.
Anyway, not advocating for anything here, just pointing out that I had the same worry about supporting a rich vocabulary of verbs, but then kind of realized it didn't matter because all verbs you want can be nouns. If you are using HTTP though, the REST verbs match up pretty nicely with how the protocol works, so it avoids inventing another abstraction to sit on top of it.
REST doesn't remove abstraction layers, it creates abstraction layers. Whether you do REST or not you will have an interface between client and server, which has to be documented and have a well defined set of nouns and verbs, period. Can't be avoided. Removing my choice of verbs does NOT simplify things. If my API only needs CRUD verbs that's what I'll use. No problem. But forcing me into those 4 verbs, only, ever, and always (as pure REST does) is not a help, it's a hindrance.
Anyway, I was still annoyed by the limited verbs 10 years ago after using REST for five years at that point. I even blogged about it, as I started doing HATEOAS about that time, so I really feel your annoyance. I've just discovered over time that the verb/noun thing is just stylistic, not an actual technical concern. All of your verbs can be nouns.
So what I do today is I use "REST APIs" (like in Java Spring, Axios/Ajax, etc.) but all my endpoints are named as "verbs" (not nouns), and the only HTTP verb I ever do is a "POST".
So everything boils down to this:
let myJsonReponse = api.doSomeVerb(myJsonRequest);
Programmers have had the ability to do that since the 1960s and guess what... nobody ever wanted to do it.
With the advent of HTTP (and it's fixed set of verbs and return codes), that didn't somehow invalidate all the prior decades of OOP. lol. However RESTful fanboys disagree with me on that.
Responding with a standard error code is okay for verbs that are not supported at a particular state, but it's the uniform interface constraint that forces you to keep the set of verbs small.
Also, HTTP has nine verbs: GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH, and TRACE.
Here's the thing: None of those concepts in those books are trumped once you happen to be communicating over HTTP/HTTPS. None of those books tell you to come up with 9 verbs, and make everything a noun operated on by those 9. That's silly.
HTTP layer has a place in the tech stack. Let it do what it does. Your API RPC layer is a separate abstraction layer, that also needs to exist. Trying to merge RPC down into the HTTP layer is silly and is cramming a square peg into a round hole, just because the round hole already existed.
1) Being relatively fast for external developers to come up to speed with
2) Allowing (and in fact pressuring) you to make non-breaking evolutions to your API without it devolving into a total mess of confusing semi-overlapping operations
3) (As a result of the other two) Minimizing the bidirectional communication needed between groups of developers
The major con is that they tend to require quite a bit more work and code to implement than operation-oriented APIs, especially when you are the only client.
Others will certainly have different opinions, but the view I've been forming over the last few years is that resource-oriented (noun-oriented) APIs should be considered the default for "external" interfaces, while operation-oriented APIs are much better-suited for "internal" interfaces. Do note that, in this model, deciding what is "internal" vs "external" should be an active design choice. It should be made based on your expectations for code ownership/control, communication frequency, and project structure.
I think what you are conflating is "good documentation" and "well designed APIs" as an attribute of REST, when it's really just an attribute of good engineering.
Engineers have used functional interfaces for decades and there's just nothing at all in REST that's any kind of improvement over functional. There's a reason "functional programming" is a thing and "nounical programming" isn't even a word.
Pick up any book on OOP and try to convert all the "operations" (method calls) in the book into CRUD methods for every code example in the book. It's doable from an information theoretic standpoint, but the book would become a completely unreadable clusterfk, for precisely the same reason that REST is so awkward. Doing an API with a predefined set of generic verbs is just silly.
It's worth watching from the beginning, but I've linked to the relevant timestamp (8:30).
Why?
Because your application is going to have thousands of nominal states, and each one is going to need to support all of the verbs because of the uniform interface constraint.
Why a uniform interface?
A lot to say about this, but basically, the set of verbs is an abstraction of the state machine that is your application. If you have a million states and a million verbs, then you have no abstraction. If you have ten states and a hundred verbs then you have too much abstraction (i.e. you ran afoul of YAGNI). A good degree abstraction is somewhere in between, but if you care about scale (which is the raison d'être for REST), then the size of set of verbs is going to have a logarithmic relation to the size of the set of nominal states.
If I need to delete users I want a function called "deleteUser" (for example) and it will use an HTTP post to send up info, and it will stream back the response. Period, full stop.
An HTTP "post" is your 'backbone'. Nothing else about HTTP needs to creep into your actual domain specific API language of method names in your RPC vocabulary of verbs.
Also if non-HTTP REST can exist, that's fine, but I'm writing web apps so I will be doing HTTP-posts because, as Fielding himself would say, why redesign something that works.
Using your example, you'd have two states: `PrepareDeleteUser` and `DeleteUser` where the latter is only reachable from the former. PrepareDeleteUser will check that the all preconditions are satisfied (e.g. that the current operator has permission to delete the user). Now, you may not choose to reify these states so directly (i.e. you'll just have a deleteUser function that does a check for the preconditions), but they must exist in a robust application nonetheless.
In REST we name our states so we can drive the state machine by using the names (following hyperlinks). Why? Because, among other things, this keeps the client decoupled from the server by letting the client be in control of when to effect a state transition, but keeps the server in charge of what transitions are possible.
I need to attend to some real-life concerns at the moment, but I hope to get back to this discussion soon.
Cheers!
1) Everything is a noun. 2) You have a finite set of pre-defined verbs.
In my opinion, everything is not noun, and I don't want any verbs pre-defined by the stack.
I will always continue to use HTTP POST as the 'transport mechanism' to send a JSON request up and get a JSON response back. It's the simple and obvious way to do things, and after fully understanding REST (trust me I do get it, fully) my opinions remain unchanged.
There's a reason "functional programming" model dominates all software architectures, while state machines are rarely used in API design. All of the reasons functional programming is good on the same machine STILL APPLY even if the machine you're calling is remote.
And just because you're riding on top of HTTP over the web is no reason to intermingle your application layer code into HTTP-related stuff. Your API should remain unchanged even if HTTP were replaced by something else. Nothing about HTTP should affect one single verb or noun (function or object) in your entire application API...and if it does it's because you've been brainwashed by the REST cult. :)
I'd like to read more about this way of thinking about it. Do you have any recommended resources?
The big idea behind scalability (IMO) is that we want the pain of maintaining a system to grow logarithmically with respect to the size of the system. Now, size can mean many things (number of customers, lines of code, etc.), but pain is almost always complexity. A potent cure for complexity is symmetry, because every time that we discover a new symmetry, half of the complexity goes away. One way of finding symmetry is to look for invariants.
Roughly speaking (very roughly), having lots of possible states is good (the more states, the more powerful/featureful the system), but having lots of state transitions is bad (especially with respect to security). REST “verbs” help to control complexity by imposing invariants on state transitions. For instance, one good invariant to enforce is that a GET transition mean that a state can always be a start state, whereas a POST must always have an antecedent state. Thus, a REST verb is just label for a set of invariants, and we’re free to choose whatever set of invariants we want. Obviously, the more invariants you have, the weaker they are since an invariant is supposed to be unchanging; i.e. if the size of set of invariants is close to the size of the set of states, then you effectively have no invariants.
My who point is that having a fixed set of verbs is about as awkward as it gets in software design, even if there were 100 to choose from.
I tried to implement an IMAP server a few years ago, but otherwise I don't know much about it. However, I do recall that Mark Crispin admitted that he wasn't a very good API designer, and that much of the complexity of IMAP was due to it being intertwined with the complexity of MIME. But, I can't find the sources for those claims at the moment.
I really like the idea of each app getting it's own specialized backend. Have you heard of the BFF pattern?
https://philcalcado.com/2019/07/12/some_thoughts_graphql_bff...
I've never used GraphQL yet but I know I do like it. Most of what I've done has been a mix of OSFA and BFF. RPC API design is more art than science, but definitely everything about REST is wrongheaded, inside out, upside down, and ass backwards. lol.
First, nowadays altering the DOM is way more responsive than loading a new page, so no one really wants HATEOAS -- not even users, but especially not the sites we like to visit because they don't want to put out public APIs anymore. For non-browser app APIs (public or private), well, they can be the same, just driven by JS when in-browser. This... is sad. But this is a fact of life now. Just watch Tom Scott explain why the APIs went away, and when the APIs went away, so did HATEOAS (https://www.youtube.com/watch?v=BxV14h0kFs0).
Second, there's a lot of APIs that needn't have anything more than one end-point -- no links to traverse, no HATEOAS. For example, a certification authority can take a CSR and authentication and return you a certificate -- one end-point is all you need, and other than that, the API can be RESTful in every sense. And then there's APIs where links aren't necessarily abundant or interesting.
Third, HTTP kinda sucks anyways if you're dealing with databases. There's no nice RESTful way to construct transactions unless you put the RDBMS smarts into the client (JS again), which you can't do if it means trusting the client (it does). So right there, REST is broken anyways. Sure, if you're distributing your database, you need to deconstruct your transactions anyways, but you're not going to trust a user-agent to get that right, and anyways, you can't really do that with a HATEOAS interface.
Put another way: show us how to build a secure application with REST (including HATEOAS) that a) users will enjoy, b) companies want to build, c) with complex transactions. If you do, we might all get our pitchforks out and protest for HATEOAS. Searching for examples of HATEOAS, I don't find much. Sure, for proprietary, corporate apps HATEOAS can be meaningful, but even there, I suspect for devs it's easier to just define APIs and drive all in-browser interaction via JS.
The DOM is irrelevant wrt HATEOAS. HATEOAS is just a way to decouple clients from servers. You get that by not resorting to hardcoded links, and instead getting your server to supply links to clients in the form of links driven by link relations. HATEOAS is capabilities discovery. HATEOAS is API versioning without explicit versions. HATEOAS is a documented and discoverable API. That's it.
It's also irrelevant to HATEOAS if you have 1 our 9999 links. You set a root document with a link. That's it.
HTTP is completely irrelevant to HATEOAS. HATEOAS is an element of an architecture style. You can do REST with UDP if you'd like. And no, you can easily do transactions with REST over HTTP. No need to mix DB stuff on the API.
Finally, you let it clear that you don't like REST or HATEOAS. That's ok. Yet, your personal preferences don't mean something is broken, specially if they are derived from misconceptions, confusion and ignorance.
Only an intelligent agent could meaningfully navigate from one state to another, which is roughly equivalent to a clicking on URLs on static sites, which is how most websites work or at least used to work.
When you manipulate the DOM to implement interaction without any "hypermedia links", there is an impedance mismatch here and HATEOAS is not a good choice for user interfaces anymore.
> HATEOAS is capabilities discovery. HATEOAS is API versioning without explicit versions. HATEOAS is a documented and discoverable API. That's it.
You can't discover capabilities without prior knowledge unless you are an intelligent agent. That's why HATEOAS is a really bad choice for APIs. You effectively have to implement the agent "discovering" what you expect to be there, instead of just explicitly asking for what you need. It's not just pointless, it's a waste of time.
That's patently wrong, and ignores basic RESTful standards such as HAL. The DOM is irrelevant and meaningless in the context of HATEOAS. There is no DOM at all. There is a resource, and the resource is tagged with link relations. That's it.
Just because the word Hypermedia" pops out this does not mean HATEOAD has anything to do with HTML.
> Only an intelligent agent could meaningfully navigate from one state to another, which is roughly equivalent to a clicking on URLs on static sites, which is how most websites work or at least used to work.
This is where you're objectively showing where you're getting it wrong. REST I'd about resources and resources representations. Your "URL" is just a specific resource, and that resource is tagged with link relations which point to to other resources. It's the resource that is linked, not the content of the resource.
> When you manipulate the DOM to implement interaction without any "hypermedia links",
Again, you're showing where you've been getting it wrong. You do not manipulate any DOM to "implement interactions". You just get the link relations of a resource. That is all. Some HATEOAS formats even pass link relations through HTTP headers. The concept of a DOM is entirely meaningless in REST. There are only resources, resource representations, and link relations. That's it.
Again, just because HATEOAS has "hypermedia" in its name that does not mean it has anything to do with HTML.
That's an opinion on the usefulness of HATEOAS. I'm well aware that misguided developers keep inserting HATEAOS where it provides no value. It's just annoying.
Realistically, the only useful thing you could do with HATEOAS-style data and an agnostic client is to generate a (rather crappy) UI for an intelligent agent to navigate.
This is clearly what Roy Fielding had in mind as well, where I quote from his dissertation:
"The name “Representational State Transfer” is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use."
> Just because the word Hypermedia" pops out this does not mean HATEOAD has anything to do with HTML.
It may in principle be not specifically tied to XML or JSON or HTML or web browsers, however in practice that's the only domain where it is actually used. Therefore, alternative ways of doing things in that domain are relevant when talking about REST.
> You do not manipulate any DOM to "implement interactions".
Here I'm talking about how many modern web applications actually work, not how REST works.
> This is where you're objectively showing where you're getting it wrong. [...]
The text I elided in that quote says nothing about how GP is wrong. Saying "objectively" doesn't make it so. You have to back up your arguments.
In a way you're quite right: links don't have to be URIs, hypermedia doesn't have to be HTML, and links don't even have to appear in the media when you can construct them algorithmically (in the last case you can argue that even though they are absent in the media, they are notionally still there). However, GP is right that only an intelligent agent will be able to use useful things with links of types they don't already have baked in logic for doing things with, and this is really the key problem with HATEOAS: it's too human-centered, and implicitly so.
Anyways, be kind.
The DOM thing was answered ably by u/gridlockd separately, so I won't say much more about it other than this: in a modern web app you won't necessarily see links in the resources fetched by JS -- you might need to know how to transform that content into links (if there are any), and you might find that embedded as logic in the JS. That's not really HATEOAS unless it's documented and stable.
There is no "rest of REST" once you omit HATEOAS. That assertion makes absolutely no sense. HATEOAS is the whole basis of REST. If you take HATEOAS away, all you get is plain old RPC.
> The DOM thing was answered ably by u/gridlockd
That response is packed with errors and misconceptions. Instead of paying attention to echos of your errors you would do better to discover what REST and HATEOAS actually is, because both of you have repeatedly shown that your grasp on the subject needs a lot of work to iron out a lot of basic misconceptions.
> in a modern web app you won't necessarily see links in the resources fetched by JS -- you might need to know how to transform that content into links (if there are any),
That is the sort of comment that makes it quite clear that you have no idea of what you're talking about. Resources and resources representations are not platform-dependent or even format-dependent. REST is not making a fetch(), and HATEOAS is not a HTML document with <a> tags. REST is an architecture style defined by HATEOAS. It doesn't care about HTTP or TCP or even IP. It cares about resources and resources representations, and cares about link relations associated with resources. What you decide to do with JavaScript is irrelevant. The only thing that matters is what are your resources and where are the link relations, and HTML or JavaScript plays no role in any of the concepts.
> It’s not obvious why Fielding thinks anyone would ever attempt to build such a thing given that the web already exists; perhaps in 2000 it seemed like there was room for more than one distributed hypermedia system in the world.
It’s worth remembering that Gopher was still a common thing in 2000. https://en.wikipedia.org/wiki/Gopher_(protocol)
Then Java applets failed, ActiveX got pwned into oblivion, people started using JS as a replacement runtime, and that killed absolutely everything else.
When I got into the company I asked people what REST means and asked about the 'links within the response' trait. No one had heard of it.
This article is exactly what I was looking for at that time.
FIOH!
I wrote a few API articles last year and people love them. I didn't know crap about API development when I wrote them, I just read Fielding's work and summarized it.
https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding...
MVC was originally used to describe a design using Smalltalk UI widgets as controllers and charts and other similar displays of data as views that worked with business logic stored in the model. State flowed only in one direction, from controller to model to view.
Web MVC completely overthrew that approach and replaced it with something very different with the same name.
All UX was moved to the view, controllers became HTTP endpoints. Communication became bidirectional at both interface layers. View talks to the controller which talks to the model.
When people say they use REST APIs, they aren't.
When people say they are building MVC applications, they aren't.
Except they are. The new meanings that evolved have replaced the original meanings.
> “state transfer” in “Representational State Transfer” refers to navigating a state machine using hyperlinks between resources (and not, as many people seem to believe, to transferring resource state over the wire).
but this line from Fielding's thesis reads -
> REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource.
.. which is closer to the alleged false belief?
My pet theory is that rest was popularized by Rails. If you look at trends [1], rest itself shows up as a super slow trend ramp that only now is starting to diminish... But rails seems to have had the peak of its popularity between 2006/2007 [2], which happens to be the time Rails 1.2 came up with "restful routes" support. Even if this theory is correct, it begs the question how did the Rails developers come in contact with rest themselves and how did it happen that the whole thick thesis derived in just a simple HTTP routes convention ...
1: https://trends.google.com/trends/explore?date=all&geo=US&q=%...
2: https://weblog.rubyonrails.org/2007/1/19/rails-1-2-rest-admi...
"You've tried the REST, now try the BEST!"
SOAP 1998
Fielding's Dissertation: 2000
What is this garbage?
Public APIs as we see them now were not a thing in 2000. There were talks about web services, but that was really different story (see WSDL). SOAP became a standard only in 2003 and it had different set of constraints and purpose.
Instead, only a few ideas from REST that appeared useful were adopted and made their way into real-world APIs that actually solved problems. Most of these ideas are not actually net benefits and cause extra issues, but they look nice on the surface, people built around them, and so they stuck.
The more attempts are made at implementing the more useless parts of REST (like HATEOAS), the worse an API becomes to use.
So please, do less REST, not more. If possible, ship a library for your API for the major languages and don't leak any of the REST bullshit into it.
Fielding's paper was never meant for webapp developers.
The only thing here is: it wasn't intended to be used this way.
I see it being called an overload, but I see no alternatives..
This article adds little of value, or even doesn't highlight or enunciate the disadvantages of using REST for everything.
And on the other hand, the advantages are obvious
Some APIs make rather poor use of HTTP, using it as a glorified RPC mechanism. Done poorly, this can make caching hard or impossible.
A fair number of self-proclaimed "REST" APIs seem to do okay on the HTTP verb part of things, using GET/PUT as HTTP intended, but they insist on naming resources by "IDs" or something, and to then fetch the named resource, require the user of the API to manually construct the URL themselves. This is antithetical to what Fielding's REST proposed, which is that the URL serves as a universal mechanism for naming resources, and that end clients don't need to know anything about how to construct URLs, because they can just follow the one they are given. (And the server can do whatever it wants with URL layout.) Fielding himself notes this on his blog[1],
> A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server).
For practical examples of this, the Azure API is significantly hit or miss here. Some references to other resources are in URI-references (this is a good application of REST) but sometimes it is just a string name and you have to know, out of band, how to construct a URL to that resource.
I'd recommend the ACME API as the best application of REST that I am aware of.
[1]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
I think it very clearly states that REST is not that well suited in situation where we actually want RPC.
> I see it being called an overload, but I see no alternatives..
Well, there are alternatives when RPC is needed, e.g. SOAP.