Roy Fielding's Misappropriated REST Dissertation(twobithistory.org)
twobithistory.org
Roy Fielding's Misappropriated REST Dissertation
https://twobithistory.org/2020/06/28/rest.html
184 comments
In order to better appreciate the idea you have to understand the context of addressing during that time. Addressing was a major factor in the architecture implemented at the time, for example CGI which executed dynamic scripts at the web server from a known fixed location.
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.
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.
Yes, CGI is a good call out, from architectural style perspective it is equivalent to RPC.
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.
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.
People are far to concerned about whether an API is "true REST" or not, as if being "REST" is some kind of mark of quality. But nobody have yet made a convincing case that HATEOAS is even particularly useful for machine-to-machine integration. But a number of properties of REST are very useful for API's, for example the focus on data and URL's and the explicit distinction between methods which are safe and methods which have side effects.
The conversation should be about what patterns help us build useful API's, not about canonical or heretical REST.
The conversation should be about what patterns help us build useful API's, not about canonical or heretical REST.
Yeah.
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.
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.
> 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
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...
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...
Actually, you agree with half of the people here who claim that REST wasn't about designing API. Because it isn't. The other half who claim that REST is an architectural style for API still don't understand what that dissertation was about, and it wasn't about 2 web apps communicating with each others.
We already have plenty of protocols for that, REST isn't one.
We already have plenty of protocols for that, REST isn't one.
Excellent quote- "We already have plenty of protocols, REST isn't one"
> 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.
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.
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.
It is worth a blog post, one unfortunately that I don't have time to write.
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.
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.
Thanks for taking the time to reply. I just saw it.
While I think we all recognize that the approach, to handle data and not live objects, is different, you seem to have missed the core objections, which are that REST is and was widely misunderstood and FIOH might as well be the true protocol in widespread use today.
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'.
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'.
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.
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.
> 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.
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?
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?
[deleted]
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...
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...
https://8thlight.com/blog/jason-desrosiers/2018/05/30/the-hy...
> 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.
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 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...
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...
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.
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
FIOH from the article is better ŧhough
> 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".
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".
>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.
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.
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.
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.
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.
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.
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.
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.
Proper REST is quite hard concept. I think that people just extract key useful features and use those. For me REST is HTTP + JSON + particular URL convention + using HTTP features as much as possible (e.g. use standard HTTP headers instead of custom response fields). But features like URL discovery: I never understood why someone would do that. API is consumed by code, not by people or AI. URL discovery would be useful for protocol without documentation, but that's hardly a useful replacement, just write a documentation.
> But features like URL discovery: I never understood why someone would do that.
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.
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.
> instead of HTML you use a custom markup language
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.
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.
REST doesn't have any official normative spec, there is no proper REST at first place. This is why I never liked the idea itself.
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.
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.
> And let's be frank, very few businesses are actually really doing representational state transfert.
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)
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)
> Every website on the Internet is doing representational state transfer. REST describes the interaction of browsers with websites. It's not meant to describe APIs for use by machines.
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.
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.
> 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.
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.
Actually no that's incredibly hard, because you have to specify somehow every possible relationship within your domain and write an engine which can use them appropriately.
REST is defined in Roy's dissertation, no? Sure, that's not a spec, but since rest is an architectural paradigm more than a concrete standard, it seems appropriate.
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.
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.
> JSON + particular URL convention
It's worth noting that those are not extracted from Roy's REST, because they were never in it.
It's worth noting that those are not extracted from Roy's REST, because they were never in it.
[deleted]
It doesn't really matter what the dissertation says. Because we don't follow dogma. REST has evolved. Whether people understand it or not isn't that important, what matters is the patterns that emerge that people are actually implementing on working applications.
It's just a naming problem where "REST" is used today for APIs that are almost the opposite of what Roy meant by "REST".
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 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 like the word "literally" being used to mean "not-literally".
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.
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.
Literally came from quoting texts (usually the Bible). In the oldest uses, we are asking if a quote is literal, as in “part of the Bible”. Usage from the original form diverged pretty much immediately to mean both: in the sense of actually happening; and, in a hyperbolic sense. None of the three uses is any more “correct” as the other; all have been part of English for >300 years.
My contention is that there isn't really much divergence. All of these are natural uses of the single sense of "true to the words". True to the words [of the Bible], true to the words [of description that follows], and a hyperbolic use of the latter.
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.
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.
Huh. I like this interpretation!
I have actually bought into the hypermedia part of REST and I would still agree. The few who use the term REST to describe hypermedia / hateoas are vastly outnumbered by the ones that don't.
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.
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.
[deleted]
What matters is HATEOAS, arguably the starting principle for REST. The whole point of it is that you can follow URLs as links to reach new app states, and discover these dynamically from a page/resource. As in loosely coupled: it's not agreed up-front or out-of-band what's in an URL. What's being practiced instead almost always is that RESTful apps flaunt their "pretty URLs", and advertise these as "API" (making it two wrongs, since it's neither an API nor REST). Squeezing message payloads into URLs only is worth it if you're actually using these URLs in a hypertext context; as a general RPC encoding mechanism URLs make zero engineering sense (have no types, are needlessly/comically limited in capabilities, etc) when your only consumers/producers are programmatic services and clients anyway. What hurts is that so many RESTful apps are using "patterns" dogmatically and in a cargo-cult way, when to me they're just demonstrating they haven't understood the whole concept at all in the first place.
Pretty URLs do not contradict hypermedia designs. They may leak abstraction, but they can be a convenient implementation detail, decoupling access management and routing from processing the request.
REST is a very specific idea about exchanging states of resources rather than sending commands. The idea did not evolve and it is still useful to talk about it and use it the way it was intended.
I stopped using the term REST for anything I've worked on/with years ago. I just call them Web APIs and no one has ever cared beyond that. REST as an idea is still ineresting, REST as a buzzword feels as dated as "Web 2.0" at this point.
I think this really is the correct approach. I have come across so many differing interpretations of what is properly “RESTful” over the years. Even worse, I have found myself in technical discussions where we were more focused on following proper RESTful API principles rather than simply going with what works best for our use case.
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.
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.
There's a dissertation and thousands of articles(one if which this comments section links to) that go into all the minutiae of a "proper" REST implementation. My comment poses the idea that an understanding of the proper or pure implementation isn't as important as the broad concepts that you are saying define the whole idea of REST. On the crux of the argument, we are in agreement - those academic details don't really matter.
The thing is, nobody can agree on those broad concepts because they are too vague. On every technical interview I’m asking one question „what is REST?“ usually followed by another „how is different from RPC?“ The answers Usually differ so much, that there’s no way to understand what kind of API these people are describing. It’s like in that tale about six blind men, describing an elephant after touching different parts of its body: one said elephant is like a snake, because he touched only the trunk. Another compared it to a tree after touching a leg. And so on.
> It doesn't really matter what the dissertation says. Because we don't follow dogma. REST has evolved.
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, "REST" has devolved. REST from the original dissertation is more flexible than any "REST level-X" APIs you'll see in the wild.
A similar case would be OOP. The original idea was broader and more dynamic. But OP has a point: the adoption of these things are useful even if they move away from the original core idea. We should revisit these original ideas and perhaps learn again from them. Sometimes there are things that wasn’t adopted, something we missed, that we can now use to solve problems in a more specific context.
> The original idea was broader and more dynamic.
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.
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.
Right, I was referring to the ideas around Smalltalk.
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.
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.
> 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".
I think we're starting to come full circle there, with static type annotations and JITs optimizing with "hidden classes".
I agree. Fielding's dissertation was exactly that - an academic dissertation. A lot of what it proposed wasn't even possible given the languages, software, and protocols. What's important now is that there are REST-ful qualities that people understand and agree upon and even more importantly, future specifications like GraphQL are more rigid and more practical. The industry has learned its lesson.
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.
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.
It does matter what the dissertation says if it becomes an orthodoxy, and people follow it to the letter as a way of deferring to expert opinion on how to design APIs. Deferring to expert opinion usually is, and always should be, a good plan. Here, it's a little interesting to discuss whether that's the case.
I would say it always should be a good plan to defer to expert rationale but not opinion. I expect my experts to explain the benefits and drawbacks of following best practices not just assert that something is a best practice. When somebody follows my advice without asking why they should, I start to worry they aren't thinking critically and realize that now all the onus is on me to understand whether the shoe actually fits.
Yes, it's evolved into a steaming mess which people still believe is based on some pure idea of what is REST and what isn't, whereas what this article argues, i.e. that we're completely wrong about that, clears up a lot of things for me because if we were really basing this on something that had been fully thought out and fully comprehended and explained why is it that I've spent ten years writing "RESTful" APIs and ever once even heard of Fielding, let alone Fielding's dissertation, and never, ever, ever have I been able to find something which explained what "RESTful" actually means in terms that related to what anybody was actually trying to do with it.
I've been arguing for a while that we should stop pretending. I'm glad I'm not the only one.
I've been arguing for a while that we should stop pretending. I'm glad I'm not the only one.
> It doesn't really matter what the dissertation says. Because we don't follow dogma. REST has evolved. Whether people understand it or not isn't that important, what matters is the patterns that emerge that people are actually implementing on working applications.
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.
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.
Over the years, I've seen a lot of people claiming that they understand what Fielding meant and trying to explain his ideas. Then I've seen him dismiss those explanations and examples. What I would have loved more than anything about REST is to see an implementation of those ideas by Fielding himself in some practical project.
As noted in the linked article, arguably the most notable implementation of his ideas was the HTTP spec.
He wasn't suggesting people build APIs; he was suggesting people build websites.
He wasn't suggesting people build APIs; he was suggesting people build websites.
For websites, 99% of them used only GET or POST though. POST was only done via forms, and even then a large number of websites used GET for form submissions.
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".
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".
Well, yes?
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. :)
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. :)
The problem I see in trying to understand REST is that everyone is always trying to explain what it is whereas simply SHOWING what it is would seem so much easier and effective.
Show me a REST API! Better, take a popular API and show me how it would be as REST.
Show me a REST API! Better, take a popular API and show me how it would be as REST.
Some classic examples are AtomPub [1] and OData [2].
[1] https://bitworking.org/projects/atom/rfc5023/
[2] https://en.wikipedia.org/wiki/Open_Data_Protocol
[1] https://bitworking.org/projects/atom/rfc5023/
[2] https://en.wikipedia.org/wiki/Open_Data_Protocol
http://oreilly.com/catalog/9780596529260 chapter 9.2.3
http://oreilly.com/catalog/9780596805838 chapter 2
http://oreilly.com/catalog/0636920028468 chapter 5
http://oreilly.com/catalog/9780596805838 chapter 2
http://oreilly.com/catalog/0636920028468 chapter 5
None of these links are specs or reference implementations of what a perfect REST API is. If there is no such thing, then there is no such thing as a REST API. You linked to non normative content, thus opinions.
So please link to the REST specification if it exists or the reference implementation of REST.
So please link to the REST specification if it exists or the reference implementation of REST.
GGP did not ask for specs, reference implementation or perfection. What's the matter, why do attempt to shift his goalposts for me?
Edit: I just read your other comments. You just want to have an argument. Bad user, no cookie!
Edit: I just read your other comments. You just want to have an argument. Bad user, no cookie!
> GGP did not ask for specs, reference implementation or perfection. What's the matter, why do attempt to shift his goalposts for me?
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.
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.
> Show me a REST API!
https://petstore.swagger.io/ is an example.
Quite a few companies use a similar format to document their public APIs.
https://petstore.swagger.io/ is an example.
Quite a few companies use a similar format to document their public APIs.
This is an excellent example of how the word "REST" in its common use tells you absolutely nothing about an API. This API certainly does not look like a Fielding-REST-API, and it doesn't even look like a programming-blog-REST-API (in my experience, bloggers just like to use "REST" to mean "HTTP + JSON + no RPC").
Why can't we just call this an "HTTP API"?
Why can't we just call this an "HTTP API"?
Where is the media type definition?
Where is the single entry endpoint or the response links driving application state?
Where is the single entry endpoint or the response links driving application state?
`uploadImage`, `createWithArray` and `createWithList` also read suspiciously like RPC endpoint names. Not that one should depend on such URLs having meaning in a REST system, but this is arguably more egregious than the SocialSite API (http://web.archive.org/web/20090123123719/http://wikis.glass...) that Roy Fielding was tearing into in the blog post linked upthread.
I have stopped asking people I work with. Nobody seems to know who Roy Fielding is or have read the paper. It is no surprise nobody knows what REST is.
The consensus seems that REST is SOAP but with JSON instead of XML and uses HTTP methods to... I guess to keep everybody annoyed.
The consensus seems that REST is SOAP but with JSON instead of XML and uses HTTP methods to... I guess to keep everybody annoyed.
The great irony with soap is the whole point (iirc) was to avoid having to even look at the XML and just have your IDE and language tooling let you treat web services as libraries. If we had just swapped out XML for JSON (to please the ridiculous syntaxists that always plague technology choices) and maybe had someone write “SOAP: The Good Parts” to ditch some of the more “ambitious” subspecs we probably would have been better off. The book could have even had a clever title like “Clean SOAP” to ensure it caught on in our fashion-driven industry.
I'm pretty sure every technology that promised "you dont have to ever look at it, tooling will take care of it for you" has failed because eventually you do have to look at it, and no effort has been put in to make it look "nice"*
*except arguably compilers. Its very rare that people look at the asm output outside of specialized domains.
*except arguably compilers. Its very rare that people look at the asm output outside of specialized domains.
Sure, and this is why the syntaxists has a point about xml. As usual, it comes down to “things are hard to type” or “thinks are hard to read” when the abstractions leak.
And that is doubly stupid for SOAP which is passing messages as text.
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.
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.
Maybe it's more of a thing in certain circles but I see links to godbolt.org all the time.
You can't just swap XML for JSON because they are not equivalent, not to mention that SOAP had schemas and JSON doesn't (once you introduce schemas to JSON, you quickly realize that you gain nothing over XML).
I was simplifying, what really could have helped was coming up with better syntax for XML that was easier to read and write. I don’t care personally, but there are a lot of people who can’t get past syntax regardless of how nice or powerful the underlying semantics or abstractions are.
Agree mostly - except using HTTP methods is for simplicity and cache-ability. Not that that is necessarily well-observed or used.
It is super pretentious to list REST as a requirement on job postings when it always means writing web APIs is required.
It's interesting to see the shift on this --- you can just use the search bar at the bottom of this page with the term "HATEOAS" to see people, many of them quite notable, arguing forcefully that HTTP APIs should be hypertextual. One person compared resistance to hypertextuality to resistance to PUT and DELETE.
[deleted]
I've always been against using true REST API to build the RPC layer of a web browser SPA on top of, for one simple reason:
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.
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.
SQL is mainly four verbs, select, insert, update and delete. Not awkward.
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.
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.
If your domain is built with all nouns as a core part of what it inherently already is (like a Database being built on "records" or "documents"), then a RESTful interface for it "might" be workable, with the limited CRUD verbs.
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)
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)
> 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
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...
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...
I think a conversation between a web browser (SPA RPC) and a back-end server is best thought of as an RPC. Procedure calls are verbs if you ask me.
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.
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.
This is all a matter of definitions. For example, from a syntactic point of view, Java has three verbs for all objects: "instantiate (new)", "call method" and "access field". An object has members, and you can use those 3 verbs to interact with the members of the object.
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).
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).
I agree about creating some kind of "context object" that represents the status of a long running report, that exists for the duration of the report and can be checked later. It's a very common pattern I've used a lot myself.
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.
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.
The goal of REST isn't to be the RPC protocol. It is to be lower level protocol which uses simple verbs to transfer state.
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.
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.
> The goal of REST isn't to be the RPC protocol
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.
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.
I think that REST is the language of your API. Just like in a regular PL you normally have just a handful of verbs, as I said in my first answer, so to in REST you only need a few verbs.
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.
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.
I've said everything I know to say, 10 different ways all over this thread. It's a topic lots of people have strong opinions about for sure.
This used to be bother me a fair bit, but I learned to noun a lot of the verbs I wanted to use. You don't sell, you create a sale. You don't move, make a movement.
Right. So you bought into it, sounds like. Almost every other software developer did too. They all think they had an epiphany. They didn't.
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.
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.
Creating nouns out of your RPC is actually powerful and transformative. Verbs are transitive but nouns can be queried, handled asynchronously etc.
It feels like jumping through hoops but you end up with a more solid API for the web.
It feels like jumping through hoops but you end up with a more solid API for the web.
I like code that's simple to understand like this:
``` 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.
``` 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.
> No one will ever convince me
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.
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.
I think with functional programming developers are capable of knowing whether they're creating or updating a user.
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.
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.
You're right. No one knows what rules apply to transmogrification. That's why people use the http verbs to consistently create and edit things without having to look up the caching and idempotency rules of every random thing your API does.
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.
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.
You basically just explained how REST works. :)
* 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.
* 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.
> 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.
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 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.
If REST is "not even approximately" coupled to HTTP, then how do you explain that people attempt to use the fixed set of CRUD-type of verbs (GET, POST, etc.)? Just a coincidence I guess. lol.
> If REST is "not even approximately" coupled to HTTP, then how do you explain that people attempt to use the fixed set of CRUD-type of verbs (GET, POST, etc.)?
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...
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 consider HTTP the 'pipe' over which the data is marshalled. It has it's own error codes, it's own verbs, and it's own protocol that has nothing whatsoever to do with my API for my APP and that's the way I want to keep it.
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.
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.
I'm not sure what your point is. Yes, RPC over HTTP post is a perfectly valid style of API. It's not REST. It may in some sense be simpler, but being simple for a narrow interface isn't the hallmark of REST (being simple on an “across a whole world wide network of diverse resources that don't share common ownership and control” is more REST’s thing.)
My entire discussion has been around the assumption that there's some very specific WebApp that needs to communicate to a server (likely over HTTP too), and that I like RPC and verbs in my API.
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.
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.
I think that's a bad example, because it almost perfectly matches up with REST.
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.
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.
What bothers me is that if I have a verb called "transmogrify" in my API's domain language the REST purists will try to tell me not to use that verb, because some preexisting generic CRUD-type verb can be made to work instead. Sorry, no, that's awkward.
>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 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.
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.
Yes, we agree. What I meant is I'd have a verb that creates and returns some kind of "ReportContext" object, which sends back an "id" which I can then query status of later, for example. But no REST.
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.
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.
I didn't really have an epiphany or buy in, I just figured out a way to think about it so I wasn't worrying about verbs all of the time. Purity in all things is a problem, REST included.
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.
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.
You seem to realize that an RPC API design is totally separate concern from HTTP, and I agree with most of what you're saying, but then in your last sentence you say "REST verbs match up nicely" and can simplify your API. Respectfully, no it can't.
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.
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.
By "REST verbs match up nicely", I meant REST verbs match up nicely with HTTP methods...(there are currently about 9 HTTP methods?). That's why it's not an additional abstraction, a POST is a POST. Compared to SOAP, which is where I came to it, it's tightly aligned with the transport. (People used to advocate for SOAP saying you could use it over SMTP...). If you are going to do a non-HTTP API, REST doesn't make a lot of sense.
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.
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.
I've also done plenty of SOAP back in the day. I independently invented the equivalent of SOAP in an API back in 1998 where my RPC API used only one method, which was basically a "call(command)" for sending XML data upstream and getting an XML response (C++ app). The request XML had the "name" of the "verb" as part of the request. Basically a "command pattern".
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);
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);
Your comment illustrates how REST forces you towards an OOP-style: https://steve-yegge.blogspot.com/2006/03/execution-in-kingdo...
Sure you can definitely create an OOP-style architecture that allows only 4 functions to exist on any object (create, read, update, delete)
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.
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.
You can have as many verbs as you want, but they all need to be valid at every state of the application (i.e at every hypermedia target), because you still want a uniform interface.
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.
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.
You can read most any good book on software development and API design, and OOP, and how to create good abstraction layers, and how to name functions, and pass parameters etc.
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.
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.
My experience is that the design considerations within a system are different from the design considerations between systems. Specifically, noun-oriented APIs with few generic verbs tend to be extremely effective at:
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.
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.
One of the reasons Amazon was successful as a cloud hosting company, and offers all the services it does is because of the famous Bezos email/memo to the entire company saying every API has to be designed as if it were external facing (usable by 3rd parties).
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.
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.
“Nounical programming” is only not a word because it’s called “object-oriented” instead.
And we also agree all objects (in OOP) are operated on by verbs (methods), but REST claims that using a predefined set of generic verbs is good. It isn't good.
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.
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.
In response to the criticism of "noun-oriented" programming, check our this video: https://www.youtube.com/watch?v=BDPHfRuAFnU&feature=youtu.be....
It's worth watching from the beginning, but I've linked to the relevant timestamp (8:30).
It's worth watching from the beginning, but I've linked to the relevant timestamp (8:30).
HTTP is one particular implementation of REST that happens to have nine verbs. Another implementation might only have two or three. But no RESTful architecture will have much more than nine.
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.
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.
Most applications will have more "states" than there are molecules in the known universe. Number of states is meaningless, and doesn't play into anything.
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.
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.
I didn't say "states", I said "nominal states". These are the states that you would bother to name. They'll correspond to classes in an OOP language or discriminated unions in an ML-stye FP language.
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!
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!
There's nothing wrong with having a "PrepareDeleteUser" to pre-check if a user can be deleted. That's a legit design that you mention, but that does't validate these two silly criteria built into REST:
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. :)
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. :)
> A lot to say about this
I'd like to read more about this way of thinking about it. Do you have any recommended resources?
I'd like to read more about this way of thinking about it. Do you have any recommended resources?
Most of what I have to say comes from Fielding’s dissertation, along with spending the past several years trying to take it as seriously as possible. Other good sources are McCarthy’s Situation Calculus and all of the stuff that Lamport has written on on TLA+ (especially Specifying Systems[1]).
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.
[1] https://lamport.azurewebsites.net/tla/book-02-08-08.pdf
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.
[1] https://lamport.azurewebsites.net/tla/book-02-08-08.pdf
> Also, HTTP has nine verbs
http://webconcepts.info/concepts/http-method/
http://webconcepts.info/concepts/http-method/
Right, I simplify REST it as a CRUD model, because nobody ever uses the full 9 verbs in REST architectures anyway.
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.
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.
IMAP has many more verbs compared to HTTP, so wouldn't it be a better application layer protocol compared to HTTP for a REST API?
REST doesn't care about the size of the set of verbs, only that the set be constant. HTTP as one particular implementation of REST just happens to have nine verbs.
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 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.
For normal SPA JavaScript/TypeScript browser-based apps, I like the conventional approach of an HTTP "post" for every API call. You send JSON upstream and you get a JSON response back. Basically it's an Ajax call that gets data back to use to update the page.
Agreed! A SPA using an RPC API usually makes the most sense. I've wasted so much time over my career trying to jam functional concepts into REST resources for little gain.
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 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 just read that entire article. Thanks for posting that. I like everything it's saying, and it points out some of the major drawbacks of REST.
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.
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.
True REST API is hypermedia API and it is actually great for SPAs. It is more convenient than hardwired RPC, simplifies frontend architecture and offers much better approach to security (client does not care about security model implemented on server).
Where to start...
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.
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.
None of your points make any sense. It's as if you believe HATEOAS is something entirely different than what it really is.
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.
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.
Manipulating the DOM is not irrelevant in the sense that pretty much the only way HATEOAS could be useful is in generating a user interface that an intelligent agent could navigate.
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.
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.
> Manipulating the DOM is not irrelevant in the sense that pretty much the only way HATEOAS could be useful is in generating a user interface that an intelligent agent could navigate.
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 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 patently wrong, and ignores basic RESTful standards such as HAL.
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.
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.
The way you debate won't make you friends. When you attack the way you do, the other side just discounts what you have to say. There's a better way to do this.
> 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.
> 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.
Exactly. Thank you for putting it so well.
I only don't like HATEOAS. The rest of REST is fine, well, except for the transaction problem, but we all make do.
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.
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.
> I only don't like HATEOAS. The rest of REST is fine,
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.
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.
From the article:
> 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)
> 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)
Those were the days - the web was one of many protocols, and people were still coming up with new things, new clients, new paradigms... Stuff like Napster, GNucleus/GNutella, RSS clients...
Then Java applets failed, ActiveX got pwned into oblivion, people started using JS as a replacement runtime, and that killed absolutely everything else.
Then Java applets failed, ActiveX got pwned into oblivion, people started using JS as a replacement runtime, and that killed absolutely everything else.
This article makes so much sense and has finally explained what REST is to me. I tweeted a similar comment about thinking "Everyone says REST but no one knows what it means" earlier this year. I had joined a web company and was studying up the definition in the interview. Of course they say they have a REST API and of course it doesn't contain links. I noted that as a violation with a sense of imposter syndrome and inconfidence in myself.
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!
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 had the impression nobody ever really read his work.
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.
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.
The URL to the dissertation in that article says "2up" in it, so I took it off and yes indeed, there is a 1-up (not two pages side by side) version of the PDF
https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding...
https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding...
The same thing happened with MVC.
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.
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.
The piece states -
> “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?
> “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?
Does anybody have any insights about how rest came to be such a buzzword?
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...
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...
If you want to understand the problem with REST, just look at the discourse in this thread. REST isn’t a standard with a clear RFC, it’s a vague white paper that everyone interprets differently. It has more in common with religion than anything else. And just like religion it has wasted more productive time since it was created than anything else. I’ll never understand why such poorly defined system became the ‘bedrock’ for decades of incompatible and non-standardized APIs. And the somehow these false prophets defend it saying you just don’t understand it when they can’t agree among themselves.
It's like the classic generic Pizza Box branding slogan:
"You've tried the REST, now try the BEST!"
"You've tried the REST, now try the BEST!"
> I thought perhaps that there had been some chaotic experimental period where people were building APIs on top of HTTP all wrong, and then Fielding came along and presented REST as the sane way to do things. But the timeline doesn’t make sense here: APIs for web services, in the sense that we know them today, weren’t a thing until a few years after Fielding published his dissertation.
SOAP 1998
Fielding's Dissertation: 2000
What is this garbage?
SOAP 1998
Fielding's Dissertation: 2000
What is this garbage?
Do you need someone to google that for you? Really not a good way to ask a question.
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.
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.
True, although XML-RPC was around in 1998.
http://1998.xmlrpc.com
http://1998.xmlrpc.com
The reason for this "misappropriation" is that REST is not actually good. It never was good. You can tell if a standard is bad when the actual implementations refuse to implement significant parts of it. Had it been good, it could've been implemented as intended it would have worked and solved actual problems.
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.
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.
The title is a misappropriation of "misappropriation".
After all these years of complete REST/HATEOAS bullshit, finally, someone has the courage to say things like they really are. SOAP did nothing wrong.
Fielding's paper was never meant for webapp developers.
Fielding's paper was never meant for webapp developers.
I used to measure how annoying a REST book or post was going to be by how long it would take the author to use the phrase 'Fielding's dissertation' and followed by the HATEOAS acronym.
I see zero examples and rational/practical arguments against the usage of REST.
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
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
> I see it being called an overload, but I see no alternatives..
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...
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...
The problem isn't that REST as a concept was not intended to be used in some way, it's that "REST" as a word is used when people actually mean "HTTP".
> This article adds little of value, or even doesn't highlight or enunciate the disadvantages of using REST for everything
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.
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.
[deleted]
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.