You talking about the pseudo-restful activity/intent design? Cause I'm not gonna defend that, haha. It's a neat idea that simplifies corner cases at the expense of making a lot of common cases very counterintuitive. If the article was bitching about that, I'd take it a lot more seriously.
I dunno, I have a soft spot for Java. Yes, the verbosity can be annoying, but compare that to the scavenger hunt that modern web languages put you on when you're trying to figure out exactly who is doing exactly what.
The point of the article is that REST, as originally described, DOES NOT encourage creating a CRUD interface for every single resource. That's very typical for the simplistic Rails-style of REST, but that's not the original intent.
And that's just the point and why those of us who care about web-friendly API design get a bit "zealous." Imagine, if you will, that someone's complete argument about the pros and cons of JavaScript were based on pre-node, hell, pre-JQuery use cases. Wouldn't you expect some developers to be a bit upset that you're mischaracterizing an entire programming language?
Keep in mind, a lot of what REST is known for today came to pass as a backlash against XML-deathstar-style architectural designs for web services over 10 years ago. At the time, plenty of folks were simply porting ideas and designs from CORBA-style RPC architectures over to the web. While this is possible, you lose all sorts of advantages of an internet-centric design. And that's really what REST is about: designing applications that work with the web, not against it.
Article makes no sense to me. He is just advocating for RESTful architecture in API design, which hardly matches the controversialist tone. At the same time it completely ignores anything but the simplest read-only API with a 1:1 mapping to public resources. It's like trying to make an argument about aircraft design whilst referencing a bicycle.
I author REST APIs and try to do them properly, with mediatypes, link relations, and all the good hypermedia stuff most people avoid. Nonetheless, the author's post reflects the sort of rant I've had to coworkers at the watercooler, or anyone who'd listen.
The author nicely preempts the debate about HATEOAS and "most RESTful APIs aren't REST" and shows that the debate is part of the problem. It is. It's not a spec but an architectural style, and people are bad at design (and quite honestly, they have better things to do with their time), so broad-stroke ideas about how to lay out your system aren't as useful as a framework or codegen. So the least-effort solution wins, where you half-ass implement first three three characteristics of REST-as-seemingly-observed-in-the-wild (HTTP, JSON, templated URLs), and call it a day. If it's good enough for Stripe and Twitter, it's good enough for you.
No wonder we're in this boat; one upon a time REST was just architectural and intellectual wankery, specified in an obtuse and hard-to-read thesis by a guy who's smarter than most of us combined. It sat unknown for years, until AJAX became all the rage, and people began making API calls from jQuery to load-and-splice parts of a page for rich interactivity. Here, a public, HTTP endpoint that served easily-parseable JSON made sense. Some prominent companies released public APIs in this style, and then the blogspam began.
Within a short amount of time, REST and "RESTful" was cool and forward-looking, and SOAP was old and crufty, and any kind of ad-hoc RPC was bad. Implementing a REST API wasn't solely about usability, but also signalling that your company was forward-looking too, rationality be damned, which is why most implementations cargo-cult look the same: HTTP, schemaless JSON, templated URLs. Endless debates about HATEOAS begin, and come to an unsatisfying conclusion, because real developers' concerns about architectural purity are dwarfed by their desire to build a mostly-working API that looks recognizable to the public, and move on.
Serious players looking for reliable internal RPC develop stuff like Thrift and gRPC, which are thoughtful reimplementations of the ideas behind 80s and 90s RPC, but with the added advantage of coming from a single vendor and not committee hell. Meanwhile, Facebook also reinvents SQL in JSON and gives it to the client, what could go wrong?
Maybe the reason "REST" won is because it was easy to glean and misunderstand well enough to put out something simple and good enough. This dominance of the low-end is going to be hard to undo.
The presentation is explicitly about REST, not about pragmatic dead simple solutions.
It even quotes Roy saying "Many of the constraints are directly opposed to short-term efficiency" and that most developers don't care about goals of rest.
I think points you're making are fine, but they're acknowledged in the presentation, so your rant is unnecessary.
I think the author did a good job presenting actual (you can say academic) REST, rather than a more popular and simpler to create "JSON-over-HTTP database" pattern (which is fine, but shouldn't technically be called "RESTful").
In complete agreement here, especially your description of Fielding's thesis. If you're looking to create an architecture that scales well and permits discoverability, then it makes a heck of a lot of sense to examine and formalise the properties of real-world architectures that have achieved this.
More to the point, I think the original article's criticisms are pretty disingenuous. And his decision to ignore 'complicating factors' associated with network transport and caching: gee perhaps you're ignoring these because you CAN largely ignore these if you architect RESTful APIs. I mean c'mon, stuff like this makes me think the author is either very naive or very ignorant: The vocabulary of HTTP methods and response codes is too vague and incomplete to get agreement on meanings. No governing body - at least to my knowledge - has convened to set things straight.
Yes, yes they have. Remember SOAP? That's an OASIS "standard", it's highly specified in detail and it meets the author's desire for 'content' being independent of the transmission channel (you know, for when you want to implement a web API over two tin cans and a piece of string). He should just use that, or the OASIS ratified SOAP v2 (i.e. ebms3/as4), which is also 'transport neutral'. Have fun with that.
The rest of the criticisms basically boil down to "sometimes people don't implement it right" and "I don't understand HTTP response codes". There's really nothing that magical about REST. When you browse the web you are basically using a 'human-friendly' interface to a RESTful system. When APIs use the same architectural style it's the same thing, but for robots. That's pretty much it.
If the only flaw here is the mis-use of the term "REST", I'd say it could be worse: they could actually try to make it a RESTful API!
I too am not very fond of REST, but for slightly different reasons. While I acknowledge its benefits, I'm afraid REST will go the way of OOP in terms of fad-chasing, resulting in massively over-architected and contrived systems.
Here's the secret of REST: it's all about the information and definitely not verbs.
The author begins by confusing HTTP with REST. I understand that HTTP is probably the most common protocol for implementing RESTful architectures, but since the author is devoting so much time to trashing REST, they ought to correctly make this distinction. Hence, the complaint that HTTP verbs aren't adequate to express certain problems isn't a critique of REST, it's a critique of HTTP. This problem is present throughout the entire article.
Then, the author complains about the specifications of REST (i.e. "What a scoop in the software world" with respect to the client/server architecture). Not all applications are well-suite to client/server architectures -- those applications are not well-suited for REST. Some principles of any architecture may seem simple, but I don't think that's an inherit problem.
The author really revealed their ignorance with:
>Rest is awesome, because it is STATELESS. Yes there is
>probably a huge database behind the webservice, but it doesn't
>remember the state of the client. Or, well, yes, actually it
>remember its authentication session, its access permissions…
>but it’s stateless, nonetheless.
REST is not stateless, RESTful communication is. This just means that each request from the client contains the information necessary to create an appropriate response -- and that this is possible for all resources. That implies that issuing temporary authentication tokens is not RESTful, since an initial authentication request is required to create a second "meaningful" request. This is a desirable trait for many classes of applications.
However, all of this being said, the proposition 'REST is sometimes used inappropriately' is true, and it is interesting and constructive to identify situations where REST is being used inappropriately. It isn't clear to me that RPC calls are appropriate in all (or even most) places REST is used.
Rants like the one in this article are really toxic, simply because they make people think this is an acceptable way to approach technological problems. What would actually be useful is to:
* identify and find examples of misuses of REST
* try to create a taxonomy of REST abuses and recommendations for those scenarios
> He constructed his own interface in order to complain about it
Yes, it is contrived, but it faithfully represents many examples I've seen in the real world.
> Also, what's with the REST rant? I don't think I understand how that's linked.
Why not? It's clearly explained. The typical REST API (as opposed to the well designed REST API) is just Active Record over HTTP: /something/:id called in N+1 loops. And this emerges for the same reason as it does in the Active Record pattern; the 'central abstraction' offered by REST is mapping every resource to a URL, as opposed to mapping every row to an object.
I disagree with the article and the examples provided.
The author has left out a few key components of REST in their initial distillation. Critically:
> REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components.
So given the example from the article:
POST /articles/{articleId}/approve
This URL does not point to a resource, and the HTTP verb does not describe what action is being taken upon a resource. It's also not using the representation of a resource to capture intent.
It's also worth noting that a GET for the article would return the "status" field and presumably other PUT requests to update the article would either act directly on the article or have other vanity action URLs, making the API more verbose than if everything were done properly.
A RESTful design would be in essence CRUD. It would have a url (/articles/{articleId}) identifying a resource, it would have a representation of a resource that includes a "status" field, and changing the status of the article would involve a PUT request to the URL of the article with the desired change of state.
The article starts with this...."Designing a REST API is not easy. No, really! If you want to design an API the right way, you have to think a lot about everything, and either to be pragmatic or to be an API terrorist. It’s not just about GET, POST, PUT, and DELETE. In real life, you have relations between resources, the need to move a resource somewhere else (think about a tree), or you may want to set a specific value to a resource."
It seems like developers are making this too hard. At some point you're just sending data over http, so why does this have to be dogmatic and needlessly complicated just to match some mystical HATEOS spec that doesn't need to exist to get the job done?
This just sounds like a repeat of XML and similar debacles, where people tried to address design decisions outside the problem domain. XML is no more interoperable than a well-documented binary protocol. I'm sure REST is great for some applications, but this attitude that we can do all our design upfront is bad for the web. I mean, the browser just recently rediscovered interrupt-driven programming with the introduction of websockets. That's pretty embarrassing if you ask me.
> "Just REST" doesn't actually encapsulate meaningful behaviors by itself.
Yes it does: open a socket, speak HTTP, get some data back. Yeah you'll have to feed it into a JSON parser or whatever but apparently people consider that a lot of work now?
I do agree on the points with statically-typed languages. Finagling dynamic types in such a system is a PITA. But I do not see the need for autogenerating tooling if you're consuming REST from a dynamic language; all you've automated is the HTTP call and data parsing (which takes very little time to write oneself)
Maybe I've been living under a rock the past 10 years but REST has never required very much effort, either to implement or consume. Then out of nowhere I begin encountering all these weird-ass tools -- Swagger (and who the F named that one, Old Spice?), Grape, whatever. All this crazy software to do all these crazy things when... it's just HTTP and JSON over the wire :/
At some point people need to ask themselves, 'how much abstraction is too much abstraction?'
Swagger's real value-add to me is in a standard documentation format for REST APIs, but the last instance I used of Swagger made my work more difficult :/
you're right, this is really about making a good JSON api that maps CRUD operations to HTTP verbs. REST is often used as a shorthand for that, though its not technically 100% accurate.
that said, it was still a good article. I agree with the author on his best practices for JSON API design.
> Honestly, REST is a great idea. Yes, people get religious about HTTP verbs and URL structures. But you don’t need to. Prioritise clarity to humans above everything else, and you’ll be fine for the most part.
I've seen this argument before (I've even made this argument before), but I'm becoming increasingly unconvinced by it. Let me explain my thinking:
1. If there's ANYTHING that sets REST apart from a generic HTTP-and-JSON protocol, it's the focus on basing endpoints off the concept of resources and collections, and using HTTP verbs to determine the type action to be performed. (And also, possibly, internal hyperlinks, but nobody seems to actually pay attention to that part.)
2. Depending on your application, somewhere between "some" and "most" of your API traffic doesn't deal things that easily map to resources and collections, doesn't involve actions that easily map to HTTP verbs, or both. One of the most common examples is sessions. When you log in, are you creating a session resource? Is that a sub-resource of the user resources, or an independent collection in its own right? Or are you actually retrieving a session token from the user resource? When you log out, are you actually deleting that session? Or updating the session to remove its authentication?
3. It's easy to say "prioritise clarity to humans", and I totally agree, but in that case, you'd just have a /login and /logout endpoints, you'd do a POST to the former with a valid username/password to login, and a POST to the latter to log out, the end. That's super clear, and super usable, but nothing about that is RESTful. And the same thing comes up over and over again. For every time I find myself doing simple CRUD operations on a collection of concrete resources, there's 10 times I find myself needing to do complicated, ambiguous operations on things which aren't.
4. But if I relax and focus on making a clear, usable API, then almost by definition I have to do so by not being RESTful. It's easy to say that you shouldn't get religious about HTTP verbs and URL structures (and I agree), but since HTTP verbs and URL structures is 100% of what people seem to mean by "REST" in actual practice, then...in what sense is REST a good idea? It's like drinking rum and coke without the rum...and the coke. What's left? Nothing Roy Fielding would recognise, in my view.
I'm happy to entertain the idea that REST is useful when you are doing CRUD operations on simple, concrete resources (updating prices on an online store; posting comments to a blog; whatever). But in my personal experience, most people seem to view REST as the ideal way to handle making an entire API, even the bits that are clearly nothing more than RPCs triggered via HTTP.
Maybe you just skimmed the article, or he's changed it since, but he doesn't say that verbs in URLs was RESTful. He said it was better than RESTful, and I'm inclined to agree with him.
Having tried my hand at designing REST APIs for typical business systems a few times, I've noticed that state machines and transactions are everywhere. Making every resource a noun with the four basic REST verbs leads to a complex and extremely chatty design, whereas slipping a few extra verbs in here and there makes the API simpler, easier to understand, and more efficient.
> Fielding looked at the Web, and abstracted it, and calls it REST Architecture.
yeah the perfect rest protocol is the web and the perfect rest clients are the humans that navigate the action represented on the hypermedia.
that said, there's some value to be had in discoverability, even if rest grossly gloss over how to discover parameters for the action that the state holds.
And object orientation wants you to think about your API as a graph of objects, but going too far down this rabbit hole is how you end up with a mess of AbstractSingletonProxyFactoryBeans[1]. Yes, it's possible to adapt any system into a collection of resources, but the transformations necessary to do so can end up creating more complexity than is gained through only having resources and verbs. The supposed simplicity of REST can be like the simplicity of the Brainfuck language. There's only 8 commands! Easy!
And the idea that using HTTP somehow renders questions of performance irrelevant is bizarre. If Hacker News sent 10MB of uncachable CSS, spread over 100 HTTP requests, with every page load, would that be OK because performance isn't the most important goal of the web? People use HTTP because it's a ubiquitous protocol supported by virtually every device and language. Performance isn't the most important goal, but it's still an important one.
> REST became popular when it was detailed and promoted by Roy Fielding as part of his doctoral dissertation entitled Architectural Styles and the Design of Network-based Software Architectures in the year 2000. Roy is well known for his contributions to development of the web, especially the HTTP specification.
So far so good.
> Roy advocated using the request methods he helped define in the HTTP standards to impart meaning to HTTP requests.
Not even close.
REST may be one of the most misunderstood ideas in all of computer science. As described in Fielding's dissertation, REST is a software architectural style whose main idea is that hypertext drives state changes, aka Hypermedia as the Engine of Application State (HATEOAS). Fielding leaves the transport protocol as an implementation detail.
In other words, an automated agent (API consumer) should interact with an API in the same way that a human interacts with a Web site. User browses to well-known URL. Page displays content with links. User clicks on a link. And so on.
A human doesn't need to read documentation on using any particular website any more than an automated agent should need to carry service-specific instructions on using an API. Media types and hyperlinks do all the heavy lifting.
The stuff about structured URLs and response codes came later, was created by others, and has almost nothing to do with REST's central idea. It's a different architectural style altogether.
From Fielding himself:
> I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
I dunno, I have a soft spot for Java. Yes, the verbosity can be annoying, but compare that to the scavenger hunt that modern web languages put you on when you're trying to figure out exactly who is doing exactly what.
reply