A number of these points are not really a criticism of RESTful principles per se, but rather of typical REST over HTTP approaches.
1) Asynchronous APIs
There's nothing about REST that says that operations must be performed synchronously. If a client updates a resource via a PATCH method and other services are notified of the update via a web hook or a message bus (possibly including the PATCH or the full resource), the system is still following a RESTful design.
2) Orchestration / Experience APIs
A RESTful API does not need to require a separate GET for every individual resource. There's nothing wrong with implementing bulk queries that return variable projections of the server state tuned to the need of particular use cases.
Bulk modifications are trickier, especially when atomicity comes into play. But if atomicity is not a concern, then this is more of a transport problem, not a semantic one.
4) Binary protocols
Plenty of RESTful APIs (e.g., Twitter[1]) provide data in a number of payload formats. Choice of wire format is unrelated to whether or not the semantics of the API are RESTful.
I'm fairly certain that when they describe an #2) Orchestration / Experience APIs they mean queries that return heterogeneous data, that one endpoint could retrieve the results of doing many queries, with many data types ie: GET /dashboard.json, retrieving all the resources used to assemble your dashboard page.
This is very much different than the normal REST philosophy of returning only homogeneous results. Much more RPC-ish.
the normal REST philosophy of returning only homogeneous results
Is that a thing? If 'GET /dashboard.json' obeyed the caching semantics of the resources it pulled together to present, and didn't have any surprising side effects, I'd still call that RESTful, even if it returned a rich graph of interesting data.
Yeah - but what if it returned a collection of orders also retrievable from /orders/search?date=today and customers from /customers/search?lastorderdate=today&totallifteimevalue=greaterthan,100000 and support tickets from /support/tickets/search?state=open
This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports.
Not really. Returning hetergeneous data is perfectly RESTful if that is what the endpoint describes. You might want to be more descriptive in the URL, however:
What you return depends entirely on the context of your web service. If people are telling you to always return a homogenous set of results then they're wrong. You know your application better than some random guy on the internet.
I have, I agree. However the common design patterns for REST APIs encourage canonical URIs for resources, and discourage the same resource being retrieved from multiple locations - which heterogenous collections inevitably lead to.
Perhaps I should have said discouraged in the common patterns for implementing REST and REST-like APIs.
I wholeheartedly disagree with you -- you're ignoring hypermedia, an essential component in proper REST architecture.
If one correctly leverages hypermedia, you may and most likely will have heterogenous responses and relations. Side-loading relevant relations is highly encouraged and is a core component of efficient API design.
To your credit, I believe most of the information out there about REST and REST-like APIs discount how much work actually goes into building a proper REST API with hypermedia -- so we will always have half-baked design patterns that solve problems when doing REST incorrectly.
I think you are both a bit of in nitpicking mode, right?
I think the easy and normal and common path is to have canonical uri for ressources, and to serve agregated content for convenience or speed on other entry points, while adding to agregated content pointers to canonical uris.
Regarding 2) that's a 'potAYto potAHto' scenario, I think. The way I've used them in the past are to address performance concerns from customers. We have the general RESTful webservices that cover all uses cases, in that every object has an endpoint, blah blah, and the design generally conforms to RESTful paradigms.
Beyond that though, customers often request changes, additions, optimizations, etc., and as they're paying us money, we try to be as accommodating as possible. In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience.
To use the Github API for reference, to get the status of an issue, you have to query the issues for the repository, then the comments and events for the issue, and then the commit messages that are associated with the events.
An example of a non-RESTful paradigm is to simply JOIN the issue's comments and events and associate the relevant commit messages to the events so that they can all be captured in one call.
It isn't truly RESTful, but it's awfully damn convenient pertaining to customer overhead, and we still call it REST, and they don't bother correcting us.
> In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience.
This doesn't violate REST. The WWW is the canonical RESTful system, i.e. A client enters the API (a website) via a common entry point (example.com), navigates using links, and manipulates state using a shared understanding of a common media type (HTML and HTML forms). Think about it, when you go to a web page do you expect it to be about strictly one thing, e.g. when viewing a blog post, do you expect it to click a link to navigate to each comment? No, that would be insane. Does that make it non-RESTful? No. It is perfectly reasonable for a resource to be composed of other addressable resources.
An alternative approach that I've implemented in the past [0] (and found quite useful) is client-driven server-side inlining of linked resources.
What this means in practice is that the client specifies (usually with a query parameter) what related resources they are interested in, and the server can pre-fetch those resources and include them in the response.
Obviously there's some upfront development costs and your API needs to have a well-linked taxonomy of resources, but it allows the client to create these 'flattened views' on the fly with no further work on your part.
Edit: Just wanted to clarify that IMO this is a RESTful design because you are still using links to navigate your API resources, you're just writing a "smarter" server that can reduce the number of requests.
My only complaint for msgpack early on was that they didn't differentiate binary from strings, and they didn't explicitly state the format for strings (like utf8) ... other than that, it's a pretty nice format, though I don't see it particularly better than those mentioned in the article, or bson and others mentioned in this discussion.
Far simpler yet readable, there is the tried and tested bencode [0], or tnetstrings [1]. There are a little less efficient than pure-binary (especially regarding integers) and have less features, but are easier to read and write, even for a human, in my opinion.
Ah BEEP. I had a grad school project to create a domain specific modeling language that allowed you to diagram the steps for communication and between to systems using BEEP. You'd define the order of messages and the content of the messages the DSML would generate C code that implemented an API to do the communication you'd modeled.
That sounds like an amazing experience you had. I can feel the pain! Had to write a custom compiler and backend and vm for it in school. And none of us had experience in C or Assembler. The compiler created a custom bytecode assembly that the VM had to run. Then another group made an FGPA and CPU that runs the code natively. Our prof's hobby was to write an OS for that board. But somehow we managed to do it. I still wow, when I look at the code. It makes me think.. how did I write that?
1) Asynchronous APIs
There's nothing about REST that says that operations must be performed synchronously. If a client updates a resource via a PATCH method and other services are notified of the update via a web hook or a message bus (possibly including the PATCH or the full resource), the system is still following a RESTful design.
2) Orchestration / Experience APIs
A RESTful API does not need to require a separate GET for every individual resource. There's nothing wrong with implementing bulk queries that return variable projections of the server state tuned to the need of particular use cases.
Bulk modifications are trickier, especially when atomicity comes into play. But if atomicity is not a concern, then this is more of a transport problem, not a semantic one.
4) Binary protocols
Plenty of RESTful APIs (e.g., Twitter[1]) provide data in a number of payload formats. Choice of wire format is unrelated to whether or not the semantics of the API are RESTful.
[1] https://dev.twitter.com/docs/things-every-developer-should-k...