I've done REST and "rest" for many years and every single time it starts out really simple. Oh I just need the profile data so let's make a RESTful endpoint just for profile. So easy! Oh wait the profile page need data from X, Y and Z. Well we gotta be RESTful so let's make 4 HTTP calls. Oh, latency sucks on mobile and terrible networks and we have to cut down on HTTP calls? Sorry, can't, we're RESTful...okay fine ONE RPC endpoint for the profile page's information.
I think REST has it's place; it's good if you want a really intuitive way to access a very specific resource. Beyond that? For developing web apps? Almost always have to go down the RPC route and there is nothing wrong with that. Not everything has to be "RESTful" damn it!@
There's nothing RESTful about making more HTTP calls. There's no reason that there can't be representations of a resource in a RESTful API that happen to include, in the representation rather than by reference, representations of subresources.
(You probably would want to have authoritative URLs for the subresources in the representation, assuming the media type of the representation is one which supports that.)
Twilio is an interesting case. They claim all REST, yet they encourage people to generate URLs using IDs. (Twilio's API is great, apart from the incomphrensible decision to use IETF style dates, the silly "Mon, Nov 8 2009" format that only made sense in the 70s over obvious year-month-etc. style.)
I'm not sure there are any popular, really REST APIs out there.
It does, but that's an unrelated issue to the one addressed in GP, which addresses the condition where the information exists on the server side when the response is sent to know what subresources are part of the composite that is desired.
> I'm not sure there are any popular, really REST APIs out there.
The Web itself is a popular API, which provided both the motivation for defining REST and which was, itself, shaped by REST in that REST was developed in parallel with and influenced the design of HTTP/1.1.
Sub resources sure but I'm not talking about sub resources because sub resources are dead easy. This is more of a "oh we should also display resource X, Y and Z in these different spots".
If you want to be really "RESTful", TYPICALLY (and I say typically because I think every developer has a different definition of REST, lol), your URLs only align to resources so joining resources means multiple calls.
Google has an interesting solution for batch HTTP requests that could kinda be used in a way to batch RESTful requests but it's not the most intuitive. https://developers.google.com/drive/web/batch
My experience at least with using REST for APIs seems to agree with yours. REST APIs, like traditional OO programming, seem to only help in a small number of situations. I've seen some really complicated things in the name of "RESTful"ness, like crazy Accept headers for different versions of the API. And like you pointed out, each developer seems to have their own idea of what REST means.
Approaching the API design from the other direction seems better. What is HTTP offering you that is better than just using a socket? It's got a request/response thing with message framing, some handy out-of-band stuff with the headers, there's HTTPS support, it works directly with browsers, and sometimes you can even get it to work through a proxy. HTTP requests are also supported pretty easily (more easily than socket stuff maybe) in most languages.
Then, using features from HTTP where they make sense can be nice (maybe some of the status codes or ETags are useful?), but throwing the whole nebulous REST framework in there without considering how well it matches the problem or how it adds to the complexity of the solution is not a good idea.
The profile page is the resource (or a representation of the resource) identified by the URL (Uniform Resource Locator) used to access the profile page. This is true, pretty much by definition.
Whatever is designed as part of that page, and is also a resource, is a subresource.
> If you want to be really "RESTful", TYPICALLY (and I say typically because I think every developer has a different definition of REST, lol), your URLs only align to resources so joining resources means multiple calls.
URLs align to resources in that the fact that a URL is used to access something defines it as a resource. There is nothing in REST which defines resources as only the orthogonal entities in a data mode (e.g., the loose equivalent of entities in the base tables of a relational DB model.)
You certainly in many cases, for maximum flexibility, want your resources to include those kinds of things, but there is no reason -- at least none that has anything to do with REST -- for them to be limited to them.
That would be logical, yes.
> Do your storages even give you the option of updating them all together atomically?
Depends on your backend implementation. There's no reason a composite resource needs to support PUT at all, though (that's one of the reasons that you are likely to want the representation of the composite to include URLs for each component.)
There are probably good ways to solve most if not all of the problems people typically run into with REST APIs for web apps, but it could take a lot of experimentation to figure them out. It sure took us a while.
