Thanks @dgeb and @tkellen. I think I’m starting to understand the rationale, but please bear with me as I think there’s probably still more I’m missing, as I don’t think I agree with it yet.
In the case of fetching one or more servers with included, ordered events, the ordering would always be scoped by the server, correct? So then even with a heterogenous set, this would work. Then even in the case where you’re fetching data for 100 servers and in the response, you find a single server with events you’d like to inspect more closely, doing so is trivial. It’s just a dictionary lookup, rather than an expensive linear search through an array of possibly many thousands of events, checking each one to see if it belongs to the server.
I agree that it makes sense to process individual items in the primary and secondary data the same way (i.e. attributes should be in an attributes field, etc.), but it seems I wouldn’t want to process those collections the same way, because they’re inherently different. The primary data is an ordered set of requested resources, while included data should have no global order, but only one scoped by its relationship to each resource in the primary data. And this order can already be represented in the relationships field for that resource, so there’s no advantage to an array.
In my thinking, if I want to set a global order for included resources, I made the wrong request - because obviously, that’s the resource I really care about, so it should be the primary resource. For example, if I wanted to fetch events from several different servers and sort them by their timestamp, irrespective of their origin server, then I wouldn’t be querying for servers, but for events, with something like:
GET /events/?servers=22,83,29,95,12&order=timestamp. Then streaming is no longer an issue. I can even include server data if I still care about it.
The only gotcha that I can think of would be if there were ever included data that had no relationship to the primary data, which would seem bizarre to me, but maybe there’s a use case I’m not thinking of where that would be necessary.
But as I said, there’s probably something I’m overlooking or not quite grokking yet. I imagine you all have spent a lot more time with this spec than I have.