I often wonder half amused, "What Would Dijkstra Do?", every time I see the phrase referenced. It's almost like harmful has lost meaning because of the complexity of the systems of which to it refers.
Everything modern is ridiculously complex, even if it looks simple. You can't state that a single thing in a complex system is harmful without forcing yourself to re-evaluate the entire construction of the rest of the system, in which case you can either (A) determine that there is no alternative solution, or (B) the system must be altered in some other way (in which case now multiple things are equivalently harmful. Since (B) happens so frequently, this means many parts of every system are harmful precisely because the system isn't perfect yet (and every part can be minorly adjusted so long as other parts of the system are adjusted - and this latter part is never discussed (probably because the complexity involved is actually complex and someone else would be like 'dude, that's also harmful - your solution has side effects'))).
If it was easy to implement new things people would do that instead of complaining. There's a good reason things are the way they are and not some other way.
Arg. I hate the phrase. Unless you are Dijkstra you don't get to use it, IMO. Make up your own phrase. If your article is so profound and insightful your phrase will become the new jargon.
A nice article, the key ideas can be scooped by reading headlines.
REST has its limitations, but it has one nice advantage: it uses a very well-understood, totally ubiquitous, firewall-piercing protocol. I suppose it's still a huge win for any public-facing, moderate-load service. One can use compact (non-JSON) data representation and even compress headers to save bandwidth.
> REST has its limitations, but it has one nice advantage: it uses a very well-understood, totally ubiquitous, firewall-piercing protocol.
REST is a protocol-independent architectural style. (And, even if you mean the kind of RPC over HTTP that is often misnamed REST, then using "a very well-understood, totally ubiquitous, firewall-piercing protocol" -- i.e., HTTP -- isn't really an advantage over the main things it is an alternative to, e.g., XML-RPC and SOAP-over-HTTP, which use the same "very well-understood, totally ubiquitous, firewall-piercing protocol.")
You are technically correct, best kind of correct!
I'd love to see a relatively non-obscure example of REST run over to a non-HTTP protocol. REST feels sort of natural over HTTP, with all these URIs and HTTP method verbs.
XMLRPC has all the disadvantages of REST listed in the original article, but seemingly none of the advantages (like a logical, discoverable structure). Correct me if I'm wrong.
SOAP indeed has advantages — it has WSDL! When done correctly, it's delightful to work with. It's complicated and enormously more bloated, though. When run over HTTP (that is, most of the time), SOAP suffers from the same transport- and connection-related disadvantages as REST over HTTP does.
> I'd love to see a relatively non-obscure example of REST run over to a non-HTTP protocol.
HTTP itself is the prototypical example; it is REST over an unspecified lower-level transport protocol (usually, in practice, TCP/IP, but that's explicitly not required in the spec) in the same sense that REST APIs that we usually talk about are typically REST over HTTP.
I found this headline odd: "Bloated, human readable format that demands extra compression"
Is human readability a main reason for using JSON or is it a beneficial side effect?
I always assumed (rightly? wrongly?) that the reason for using JSON was that it uses Javascript's native object format and therefore much easier to serialize/deserialize and debug at the browser level.
Human-readability means low density: ASCII only uses 7 bit of 8, and most characters, like letters or digits, use only 6.
Nobody in their sane mind would `eval()` a JSON received from network, so parsing is required in any case, JS or not. A combination of lists and maps (maps being just a special-form list of pairs) can be represented in a much more compact way, especially numbers. Thrift and Cap'n Proto are definitely more compact and as fast, or faster, to parse.
I still suspect that in many cases, HTTP headers can be comparable to the message in size. A high-efficiency protocol would create a connection and avoid re-sending this information with every request — but good luck taking it through certain corporate firewalls.
You're not supposed to eval the strings, that way leads to xss. Since you're supposed to parse it no matter what, there's no difference between JSON and any other format.
Not true. While you should indeed not eval the string, once you have properly parsed it, you get a structured collection of objects and arrays that is very regular JavaScript structures. XML cannot offer the same, you get some much more abstract representation can easily be "wrong" if you don't follow the format as you extend it with more values, objects and arrays.
Not really, browsers still provide native JSON parsing ability - which is faster (and easier to implement) than most other parsing you would write inside JavaScript.
I haven't read the article yet, and while I prefer to work with JSON most of the time XML is much more human readable. And working in publishing we have a lot of XML floating around.
I agree. When I am creating raw data to be consumed later (like for a personal project or something), I often find myself typing it up in XML and then using an XML -> JSON converter to change it to JSON for my actual code.
I can just think in XML easier than remembering "Okay, so there's a bracket here, and a curly brace here, or is it curly brace and bracket? Do I need to include a key value here or not? Oh crap, I overlooked a comma again." I constantly have to send my JSON through lint, where I don't ever have to worry about that with XML.
REST is working with documents only, there is just no way to DO something (more than C/R/U/D), you need to map actions to some C/R/U/D and so on. That's a serious practical limitation.
More accurately, REST involves only transferring state. The tricky (but worthwhile IMO) part is modeling what you want to happen as the state transition or set of state transitions that it is.
Yes, and also REST does not eliminate real business concepts so you need constantly “convert” business/domain operations to REST CRUD, and this process takes too much resources. You can change business/domain of course, but I'm not sure it's suitable for everyone (API is just one of components among others).
REST is conceptually really hard and requires almost military discipline.
I'm amazed that you feel this way, because my experience is completely the opposite. Banging out the REST API portion of things is usually a mechanical wrapper around some business process in the systems I have been creating. CRUD comes into play with entity manipulation, of course, but that's only one facet and in my current case, not even the dominant one. In fact, I don't even know why you'd think you have to map business processes to CRUD at all. It almost seems like you have some religous belief about what REST actually is, much like how the article talks about "de facto" standards that are nothing of the sort.
I suppose you have strange requirements or design impositions that make your life difficult, but I caution you against believing that your use case is universal because in my very real experience, none of your opinions are supportable.
That could be his experience, though. I've run into waaay too many APIs that call themselves RESTful and are just a collection of RPC endpoints with a method="..." query parameter plus named parameters.
If I hadn't read Fielding's dissertation [1] I probably would have been lost in the weeds as to whatever the heck REST actually meant.
but seriously, who would make technology choices based on that reasoning? the thing should have it's merits, preferably for non-shitty software too. so it's not that i agree with everything the author said, i just think your rebuttal is not very good. where were your arguments anyway?
to me, if it's shit, it's shit. but i do prefer shit of the "strongly typed" flavour. when dealing with shit, i'll take any automated help i can get. but even there, of course, we can talk about trade-offs, and not absolute truths.
Even that rebuttal is too specific. The article is mainly unsupported assertions of the correctness of the author's opinions, interspersed with whining about issues that are totally orthogonal to REST.
REST, static/dynamic typing... all decisions like this are a cost trade-off.
There aren't really two 'camps', there are just comfortable positions on a scale, places where people are acclimatised to the trade-offs by their experience.
This is such a non-issue. All you have to do is look at how successful RESTful APIs have been this decade. It's easy to consume, which is really the number one priority if you actually want anyone to use your API. Anyone who has built an API will tell you that REST gets you 80% of the way, and if you need some transactional business logic the world will not end if you add a few non-REST custom endpoints.
JSON-RPC always works well and is quite simple. I often find it easier to just use JSON-RPC and clearly mark which methods are remote than to try and fit my remote semantics into correct HTTP verbs and status codes.
I agree - JSON-RPC is simple to use, parse and understand. Plus I feel it makes more sense when you are triggering computations remotely rather than querying.
At StackHut (http://www.stackhut.com) we're hacking on a platform that takes code you've written and hosts the API in the cloud over JSON-RPC. We think it's pretty cool and would love to hear from others doing interesting stuff with JSON-RPC.
This is kind of a thought-terminating cliche, though. Not that a lot of "considered harmful" essays necessarily have much substance, but actually pointing out that a lot of popular software is architected in a harmful manner and reinforces negative feedback loops, antipatterns and wrong conceptual frameworks is a legitimate thing to say in general.
Dismissing such criticisms with "It works for me," "If you don't like it, don't use it," or "Who cares about X? I just want my Y to work!" is annoying and by definition anathema to any technical discourse. They're vapid emotional arguments.
I would rather see a discussion of how a potentially destructive mechanism could be improved, particularly one as ubiquitous as REST. But I imagine a lot of these essays are not particularly well thought out; they're just an expression of momentary frustration that the author won't hold a month or even a week after publishing.
I stopped drinking the REST cool aid years ago, for pretty much the same reasons.
It's not that HTTP APIs aren't useful - of course they are - it's the religious adherence to REST doctrine that is harmful. I take the author's point to basically be, "do the simplest thing that makes sense for your use case, don't worry about how RESTful it is", which I totally agree with.
Can articles with the words "considered harmful" in the title (or the article itself for that matter) be banned? It's almost always a low effort way to get votes by taking a popular technology and finding some flaws to write an article on.
The problem with considered harmful I'm having is that so many low quality articles are using it in their titles and it really says nothing about the content other than somebody thinks some technology is bad.
RESTful doesn't mean "JSON" only. It never did and never will. People using RESTful APIs with XML.
Also i don't get many things he is saying like:
> multiple parameters for each criteria, e.g. age=10&name=John&company=Foo (but how to implement OR operator?)
I mean seriously? How would one represent a filter in a GET URL... there aren't many solutions.
Also CRUD by Design? What are you talking? REST is not a fucking standard, it's just a way to create your API, you are totally free, to use CRUD or not, your API's could still be within REST if you not use CRUD at all. You could even make REST APIs with GET and POST.
Everything he writes has nothing todo with REST. It's just a design decision.
RESTful also never meant HTTP. REST is literally just transferring resource state explicitly, via some mutually-understood representation of a resource.
JSON just happens to be much more readable as well as pretty familiar for anybody who's written code in a C-like language, and especially familiar for JavaScript developers.
I agree with the posters who say that just using 4 verbs is CRUD-oriented and semantically just not rich enough to support often complex business operations.
Right. HTTP is a (the original and motivating, in fact) RESTful protocol, not a required lower-level protocol on which all RESTful protocols must rest.
> I mean seriously? How would one represent a filter in a GET URL... there aren't many solutions.
You do have options though. You can make a GET request but send the paramaters not in the URL but in the body in JSON form. However, that would violate the HTTP/1.1 spec.
As said there aren't many options, one would be a single parameter (jira does that for JQL) and the rest somehow url encoded. However that problem doesn't only happen to rest. Everything on the web suffers from that problem (Jira is a normal Site which doesn't use too much from a Rest API (yet)) so his statement is really falsy.
> How would one represent a filter in a GET URL... there aren't many solutions.
One hole in the HTTP method space -- and it results in some weirdness trying to follow REST principles for non-trivial applications over HTTP -- is the absence of a general purpose safe method that takes a request body. (There are some in extensions, such as WebDAV Search's SEARCH method in RFC 5323, but they tend to be overly specific for general use. A generalization of SEARCH to a general purpose, content-type-agnostic query method would be a good addition (much like PATCH was) to the set of HTTP methods.
> "By building all these levels of abstractions we forgot that web is really asynchronous"
Uhh... nope. No one forgot that. Least of all the people he's chiding. Any decent Javascript / Front End Dev is acutely aware of this.
Overall, this is perhaps the most unpersuasive clickbait I've read in a long time. It is amusing, though, to see a Java dev complain that REST isn't enterprisey enough. That's not a negative, good sir, that's a selling point.
Not all business/domain logic is document-oriented. You can map any api to “documents” but result will be horrible usually. There is an excellent book — “RESTful Web Services Cookbook” by Subbu Allamaraju, it covers all aspects of practical REST API and trains very useful sense of REST applicability.
> Talking about documentation, purists claim that the only piece of information API should expose is the root URI, e.g. www.example.com/api. Everything else, including allowed methods, resources, content types and documents should be discovered via HATEOAS. And if URIs are not officially documented but instead should be discovered, it implies we should not rely on hard-coded URIs in our code but instead traverse the resource tree every time we use such API.
discoverable != must be discovered
This is a misconception and criticism I used to have. However, it's a misunderstanding of the point of HATEOAS - the point isn't that you can't use hard-coded URIs, but that any given URI should be reachable by traversal from the root URI.
In other words, it's fine to keep a bookmark to your favorite article, just make sure you can get to that article from the homepage, too.
I just built an API over HTTP, ignored all the REST rules and separated everything into commands and queries. Commands are POST and do something. Queries are GET and get something. I need to write this up.
Schema is hell with JSON etc. I don't get how you can enforce something like this cleanly in a language like JavaScript under node.js or something without piles of assertions or some weird meta-format. I'm barely managing with an informal
Also JSON is a crapfest for transferring data. Need something better than that over HTTP that is strongly typed with strong schema and has flexible binary formats other than whacking a base64 encoded string in an object or using multi-part mime.
And then you're back at RPC and protobufs or something similar. Perhaps that's the answer.
No, CQS. CQRS is slightly more complicated and decouples everything via a service bus model along with a massive software ghetto lead by Udi Dahan who I personally despise. An excellent marketer but a poor engineer. I've cleaned up two companies who bought into that idea (event sourcing, service bus etc).
Simply a command is something mutative. A query is something not mutative that returns information. There is no further specification other than that.
It doesn't mandate a bus or event queue or publishing model nor whether or not the commands are synchronous or asynchronous.
CQRS does not involve a service bus (though people like to sell them). This sounds like some people were led down very bad paths. Using event sourcing and a service bus together is frankly retarded.
Our team is currently working on building a pretty big internal API from scratch. I took a look at some popular APIs (twitter, facebook, twilio, etc.) as a starting point. All of them has its own structure of the response, as well as the way you interact with those APIs, i.e. one may use `order` field to sort the resultset, while the other one prefers `sort_by` instead. There is definitely nothing wrong about that. But most of us like standards. We try to follow specifications as much as possible, at least to make things more predictable.
Long story short - we ended up with http://jsonapi.org/ - a complete specification for building JSON-based APIs. It supports such things as pagination, filtering, sorting, relationships, etc. All of us could implement it all very easily, but only God knows what is on the mind of an engineer, i.e. whether he likes /endpoint.json vs /endpoint?format=json.
I actually agree with you on static-typing and am a huge fan of binary protocols but using "no standards" around anything is a weak argument that everybody needs to just stop. If you don't like the fact that there are no standards with a particular tech, go out there and MAKE SOME. Show people how to do it right, document it and propose it. Get some buy in. Don't just sit around going "oh woe is me, no standards"
Short of the service provider giving you a library to access their code I prefer REST over SOAP for integration work I've done. REST in my experience forces better documentation and interaction between the service provider and client. I've worked with way too many SOAP services where some dev from 8 years ago wrote the service and nobody at the company wants to go anywhere near it to modify it. On top of that there is nearly zero documentation or if it exists it's very poorly done. With REST I feel I'm forced to interact with the creator which in my experience also drives better documentation. Because who wants to answer all of my usage questions :-)
I have never run into HATEOAS in the wild but it sounds pretty cool. I hope to get to try out a service that implements that one day.
Since nobody can agree what RESTful is, and RESTful services tend not to follow any particular set of rules, indeed to the extent that most RESTful services aren't really RESTful, it's hard to get past the section titles in this as being anything other than an exhausted straw man.
The benefits of REST come when making public APIs that can be discovered with HATEOAS. People aren't doing that much yet, but I do hope it catches on, because we're not going to reach the next level of interaction between services until it (or something similar does).
I think the title misses the point a little, or at least generalises too much. REST is not harmful, it's incredibly powerful when used for the right thing. However, REST is not the correct technology choice for internal or high performance APIs.
This just in: one particular technique is not good for every use case!
Most of these complaints boil down to REST is not complex enough to capture more complex interactions. But that is its strength -- yeah, there might be some tweaks to make but if you run into a RESTful interface it is easy to get your bearings.
If you need something with more meat, pick something else.
That said, shoehorning problems into a limited number of return codes with pre-existing specific meanings is an inherent problem with the whole REST approach, I'll give the author that. It is almost never a good fit.
Is HATEOAS generally considered good? I recently had to integrate to two corporate systems.
One, the API used typical GET, POST, PUT, etc.. The second (before I knew the term applied to this) provided a single URL whose response was needed to describe the other operations. I remember instinctively hating the second. Now MY code has the burden of translating these into the specific calls. However, now we are version proofed.
81 comments
[ 3.0 ms ] story [ 133 ms ] threadIf you don't like it, don't use it.
Partially this is already happening with <whatever>-awesome curated Github repos.
> PS: Obligatory appendix: "Considered Harmful" Essays Considered Harmful. [1]
[1] http://meyerweb.com/eric/comment/chech.html
Everything modern is ridiculously complex, even if it looks simple. You can't state that a single thing in a complex system is harmful without forcing yourself to re-evaluate the entire construction of the rest of the system, in which case you can either (A) determine that there is no alternative solution, or (B) the system must be altered in some other way (in which case now multiple things are equivalently harmful. Since (B) happens so frequently, this means many parts of every system are harmful precisely because the system isn't perfect yet (and every part can be minorly adjusted so long as other parts of the system are adjusted - and this latter part is never discussed (probably because the complexity involved is actually complex and someone else would be like 'dude, that's also harmful - your solution has side effects'))).
If it was easy to implement new things people would do that instead of complaining. There's a good reason things are the way they are and not some other way.
There was a small discussion on the issue previously: https://news.ycombinator.com/item?id=9844117
REST has its limitations, but it has one nice advantage: it uses a very well-understood, totally ubiquitous, firewall-piercing protocol. I suppose it's still a huge win for any public-facing, moderate-load service. One can use compact (non-JSON) data representation and even compress headers to save bandwidth.
REST is a protocol-independent architectural style. (And, even if you mean the kind of RPC over HTTP that is often misnamed REST, then using "a very well-understood, totally ubiquitous, firewall-piercing protocol" -- i.e., HTTP -- isn't really an advantage over the main things it is an alternative to, e.g., XML-RPC and SOAP-over-HTTP, which use the same "very well-understood, totally ubiquitous, firewall-piercing protocol.")
I'd love to see a relatively non-obscure example of REST run over to a non-HTTP protocol. REST feels sort of natural over HTTP, with all these URIs and HTTP method verbs.
XMLRPC has all the disadvantages of REST listed in the original article, but seemingly none of the advantages (like a logical, discoverable structure). Correct me if I'm wrong.
SOAP indeed has advantages — it has WSDL! When done correctly, it's delightful to work with. It's complicated and enormously more bloated, though. When run over HTTP (that is, most of the time), SOAP suffers from the same transport- and connection-related disadvantages as REST over HTTP does.
HTTP itself is the prototypical example; it is REST over an unspecified lower-level transport protocol (usually, in practice, TCP/IP, but that's explicitly not required in the spec) in the same sense that REST APIs that we usually talk about are typically REST over HTTP.
Is human readability a main reason for using JSON or is it a beneficial side effect?
I always assumed (rightly? wrongly?) that the reason for using JSON was that it uses Javascript's native object format and therefore much easier to serialize/deserialize and debug at the browser level.
Nobody in their sane mind would `eval()` a JSON received from network, so parsing is required in any case, JS or not. A combination of lists and maps (maps being just a special-form list of pairs) can be represented in a much more compact way, especially numbers. Thrift and Cap'n Proto are definitely more compact and as fast, or faster, to parse.
I still suspect that in many cases, HTTP headers can be comparable to the message in size. A high-efficiency protocol would create a connection and avoid re-sending this information with every request — but good luck taking it through certain corporate firewalls.
My assumption was more related to the intent behind choosing JSON for REST, not so much related to the actual implementation(s).
I was surprised he didn't mention ease of use inside JavaScript.
It may or may not be the same to parse, say, JSON and XML.
But how is
xmlDoc=new DOMParser().parseFromString(booksXml);
newatt=xmlDoc.createAttribute("edition");
newatt.nodeValue="first";
x=xmlDoc.getElementsByTagName("title");
x[0].setAttributeNode(newatt);
as easy to use as
JSON.parse(booksJson).title.edition = 'first'
?
This advantage has nothing to do with eval(), but rather that JSON is pretty much built-in everywhere nowadays.
I can just think in XML easier than remembering "Okay, so there's a bracket here, and a curly brace here, or is it curly brace and bracket? Do I need to include a key value here or not? Oh crap, I overlooked a comma again." I constantly have to send my JSON through lint, where I don't ever have to worry about that with XML.
REST is conceptually really hard and requires almost military discipline.
I suppose you have strange requirements or design impositions that make your life difficult, but I caution you against believing that your use case is universal because in my very real experience, none of your opinions are supportable.
If I hadn't read Fielding's dissertation [1] I probably would have been lost in the weeds as to whatever the heck REST actually meant.
[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
but seriously, who would make technology choices based on that reasoning? the thing should have it's merits, preferably for non-shitty software too. so it's not that i agree with everything the author said, i just think your rebuttal is not very good. where were your arguments anyway?
to me, if it's shit, it's shit. but i do prefer shit of the "strongly typed" flavour. when dealing with shit, i'll take any automated help i can get. but even there, of course, we can talk about trade-offs, and not absolute truths.
There aren't really two 'camps', there are just comfortable positions on a scale, places where people are acclimatised to the trade-offs by their experience.
At StackHut (http://www.stackhut.com) we're hacking on a platform that takes code you've written and hosts the API in the cloud over JSON-RPC. We think it's pretty cool and would love to hear from others doing interesting stuff with JSON-RPC.
Dismissing such criticisms with "It works for me," "If you don't like it, don't use it," or "Who cares about X? I just want my Y to work!" is annoying and by definition anathema to any technical discourse. They're vapid emotional arguments.
It's not that HTTP APIs aren't useful - of course they are - it's the religious adherence to REST doctrine that is harmful. I take the author's point to basically be, "do the simplest thing that makes sense for your use case, don't worry about how RESTful it is", which I totally agree with.
Personally, "considered harmful" is in the "meh" category for me, but I'm not curating HN articles, nor is any other individual.
I thought this article was OK - certainly good enough to skim read for 5 minutes. Neither an upvote nor a downvote from me.
Also i don't get many things he is saying like:
> multiple parameters for each criteria, e.g. age=10&name=John&company=Foo (but how to implement OR operator?)
I mean seriously? How would one represent a filter in a GET URL... there aren't many solutions. Also CRUD by Design? What are you talking? REST is not a fucking standard, it's just a way to create your API, you are totally free, to use CRUD or not, your API's could still be within REST if you not use CRUD at all. You could even make REST APIs with GET and POST.
Everything he writes has nothing todo with REST. It's just a design decision.
JSON just happens to be much more readable as well as pretty familiar for anybody who's written code in a C-like language, and especially familiar for JavaScript developers.
NOt in its original spirit, but it was developed in parallel with HTTP 1.1 (see https://en.wikipedia.org/wiki/Representational_state_transfe...) and uses the same verbs (GET, POST, ..) as web browsers to transfer data.
I agree with the posters who say that just using 4 verbs is CRUD-oriented and semantically just not rich enough to support often complex business operations.
Right. HTTP is a (the original and motivating, in fact) RESTful protocol, not a required lower-level protocol on which all RESTful protocols must rest.
You do have options though. You can make a GET request but send the paramaters not in the URL but in the body in JSON form. However, that would violate the HTTP/1.1 spec.
As said there aren't many options, one would be a single parameter (jira does that for JQL) and the rest somehow url encoded. However that problem doesn't only happen to rest. Everything on the web suffers from that problem (Jira is a normal Site which doesn't use too much from a Rest API (yet)) so his statement is really falsy.
One hole in the HTTP method space -- and it results in some weirdness trying to follow REST principles for non-trivial applications over HTTP -- is the absence of a general purpose safe method that takes a request body. (There are some in extensions, such as WebDAV Search's SEARCH method in RFC 5323, but they tend to be overly specific for general use. A generalization of SEARCH to a general purpose, content-type-agnostic query method would be a good addition (much like PATCH was) to the set of HTTP methods.
Uhh... nope. No one forgot that. Least of all the people he's chiding. Any decent Javascript / Front End Dev is acutely aware of this.
Overall, this is perhaps the most unpersuasive clickbait I've read in a long time. It is amusing, though, to see a Java dev complain that REST isn't enterprisey enough. That's not a negative, good sir, that's a selling point.
discoverable != must be discovered
This is a misconception and criticism I used to have. However, it's a misunderstanding of the point of HATEOAS - the point isn't that you can't use hard-coded URIs, but that any given URI should be reachable by traversal from the root URI.
In other words, it's fine to keep a bookmark to your favorite article, just make sure you can get to that article from the homepage, too.
(I guess I would say modulo redirects as well)
I just built an API over HTTP, ignored all the REST rules and separated everything into commands and queries. Commands are POST and do something. Queries are GET and get something. I need to write this up.
Schema is hell with JSON etc. I don't get how you can enforce something like this cleanly in a language like JavaScript under node.js or something without piles of assertions or some weird meta-format. I'm barely managing with an informal
Also JSON is a crapfest for transferring data. Need something better than that over HTTP that is strongly typed with strong schema and has flexible binary formats other than whacking a base64 encoded string in an object or using multi-part mime.
And then you're back at RPC and protobufs or something similar. Perhaps that's the answer.
Simply a command is something mutative. A query is something not mutative that returns information. There is no further specification other than that.
It doesn't mandate a bus or event queue or publishing model nor whether or not the commands are synchronous or asynchronous.
Greg
Long story short - we ended up with http://jsonapi.org/ - a complete specification for building JSON-based APIs. It supports such things as pagination, filtering, sorting, relationships, etc. All of us could implement it all very easily, but only God knows what is on the mind of an engineer, i.e. whether he likes /endpoint.json vs /endpoint?format=json.
I have never run into HATEOAS in the wild but it sounds pretty cool. I hope to get to try out a service that implements that one day.
I think the title misses the point a little, or at least generalises too much. REST is not harmful, it's incredibly powerful when used for the right thing. However, REST is not the correct technology choice for internal or high performance APIs.
Most of these complaints boil down to REST is not complex enough to capture more complex interactions. But that is its strength -- yeah, there might be some tweaks to make but if you run into a RESTful interface it is easy to get your bearings.
If you need something with more meat, pick something else.
That said, shoehorning problems into a limited number of return codes with pre-existing specific meanings is an inherent problem with the whole REST approach, I'll give the author that. It is almost never a good fit.
One, the API used typical GET, POST, PUT, etc.. The second (before I knew the term applied to this) provided a single URL whose response was needed to describe the other operations. I remember instinctively hating the second. Now MY code has the burden of translating these into the specific calls. However, now we are version proofed.