[dragonwriter]

> Oh wait the profile page need data from X, Y and Z. Well we gotta be RESTful so let's make 4 HTTP calls.

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.)

[MichaelGG]

Really? I thought REST says you shouldn't assume URLs follow any pattern. So if you want to get product 123, you need to search for it, then find the URL. Instead of doing Concat("/product/", prodId).

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.

[dragonwriter]

> Really? I thought REST says you shouldn't assume URLs follow any pattern.

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.

[MichaelGG]

The web itself is hardly REST. Plus it's not really an API as in easily consumed by a machine. Most web pages, or the user agent, really rely on a human driving decisions.

Seriously, what's a popular API used by developers that's actually truly REST? All I usually see is various levels of awkwardness as an RPC message is sorta split up into various bits spread throughout the HTTP request.

[dragonwriter]

> The web itself is hardly REST.

HTTP/1.0 provided the inspiration for REST, which was defined by Fielding in parallel with work on HTTP/1.1 which it informed. The web itself is very much REST, essentially being the defining instance of the architectural style.

> Plus it's not really an API as in easily consumed by a machine.

Yes, it actually is a REST API that is actually made to be, and regularly used as, an interface consumed as hypertext by machines who access requested content by locator, choose how to handle it by identified media type, identify and either directly act on or present user options to act on related content by hypermedia links, etc. Whether this is end-user software (browsers) or unattended software (Googlebot and other spiders), etc.

[MichaelGG]

I think you are really trying to dodge the question. Spiders often employ plenty of AI to try to make sense of stuff. It's not an API in any useful sense. For instance, automating Amazon.com. Humans manage fine because underlying changes and renamed URLs, input fields, etc. are ignored. A spider can't handle that (buying items, updating kindle preferences, etc.)

But for values of API that you know I'm referring to, where is one popular, truly REST API? Say, one that includes an SDK, if you need help with the definition. The fact that no one can really point out a good example means it's irrelevant to program writers.

Also, if you're saying the web is all REST essentially by definition, then so are these POST-only APIs, but they aren't. Or it's a useless tautology.

Plus I don't see any real difference in the web of HTTP1 vs 1.1, so that whole claim is suspect too. Perhaps you can elaborate exactly what HTTP1.1 added that really changed anything except some ease of use (host header, absolute URLs, keep alive).

[sk5t]

There's a lot of academic hand-wringing about what makes real REST... but not one complete example of which I am aware. I think we're past the brink of just giving up on dogmatic RESTfulness and ought just apply the term to any reasonably sane JSON RPC-style API with out-of-band documentation for humans.

[dragonwriter]

Look, if the actual REST architectural style isn't what you want, then don't use it. But that doesn't make it useful to use the term to refer to things that aren't using it. If you want to make a JSON RPC API, call it a JSON RPC API, not a REST API.

[MichaelGG]

Agreed. I've no idea why everyone is so hot on saying REST. I think it's just a backlash reaction to SOAP and other complicated things, and they really mean "simpler interface" and RPC makes people think CORBA and DCOM? Or maybe the fact a PhD thesis is involved makes them feel more grown up. Like the backlash of shitty statically typed languages leading to people professing a desire for dynamic types instead of type inference. Or just buzzwordy, like people were saying SOA everywhere and now saying microservice.

[sk5t]

The issue is not related to any personal taste or distaste for the REST style, it's that the paucity of idiomatic, complete examples and practical references has permitted the repurposing of the term "RESTful" to mean JSON RPC, and going hand-in-hand with that problem, nobody(?) is trying to implement Fielding-grade REST APIs.

[BinaryIdiot]

> 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.

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

[nulltype]

I think some of these problems are solved by HTTP/2 multiplexing.

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.

[dragonwriter]

> 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".

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.

[BinaryIdiot]

> 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.

No that's not true at all. Your API design should not influence the user experience but the other way around and you're unlikely to change models should you have more optimal ways to presenting things.

On paper? Sure but I've never seen anything able to be split so nicely as you describe.

[prodigal_erik]

How do GET If-None-Match and PUT If-Match work? Do you assign an ETag that represents the current state of all those resources, so you can tell me if any have changed behind my back? Do your storages even give you the option of updating them all together atomically?

[dragonwriter]

> Do you assign an ETag that represents the current state of all those resources, so you can tell me if any have changed behind my back?

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.)