[nmcfarl]

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.

[pcl]

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.

[nmcfarl]

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.

[scott_w]

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:

/dashboard?type=orders&type=customers&type=support

With either some documentation explaining the differences, or even the return value itself describing what's in e.g.

{"orders": {"date": "today", "data": [...]}, ... }

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.

[sjtgraham]

> This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports.

This is nothing to do with REST. Read the Wikipedia article for a crash course.

[nmcfarl]

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.

[mahmoudimus]

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.

[gbog]

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.

No?