Great work on this module! I am working on replacing a hacky partial JSONAPI implementation with this one.

There is one feature that would block me from switching right now, which is that I need a heterogeneous collection resource that returns all nodes. Logically it would probably be

GET /jsonapi/node

The JSONAPI spec does not forbid heterogeneous collections, and there are clientside implementations (like ember-data) that are capable of consuming them.

A motivating example is a dashboard that shows the 10 most recently edited pieces of content, which could be expressed as

GET /jsonapi/node?sort=-changed&page[limit]=10

(It would also be possible to accept a POST to /jsonapi/node, and the spec explicitly says that the "type" field is required within posted resource bodies to make heterogeneous resources possible. I don't necessarily need that feature, but it seems nice to maintain the symmetry.)

Comments

ef4 created an issue. See original summary.

wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented

Hey Ed! Good to see you around here again :)

You were at the discussion at DrupalCon New Orleans less than a year ago — it must feel great to see your goals realized thanks to the power of open source? :D

Thanks for your feedback! I'll let @e0ipso answer his reasoning, but I think this is indeed simply a feature request — until now, we simply have chosen to not add support for this due to stabilizing the module being the #1 focus.

However, I am slightly surprised that this is supported, because there is literally only one casual mention of it in http://jsonapi.org/format/.

Of course, your motivating example makes a ton of sense. But it seems there's no guidance from the spec on how to deal with filtering/sorting based on fields that are not present on all types that must be returned. Do you know about any discussions/documents about this?

wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented

Also, I wanted to ask: do you mind opening a separate issue and reporting your first impressions? About any and all aspects. And specifically for the setup/installation aspect: as an occasional Drupal user, what confused you?

ef4’s picture

ef4 commented

Thanks Wim. I will write up a separate ticket of impressions.

But it seems there's no guidance from the spec on how to deal with filtering/sorting based on fields that are not present on all types that must be returned.

Sorting and filtering are a bit different, in the sense that the spec says more about sorting and almost nothing about filtering.

Regarding sorting, I don't think the problem of sorting with missing fields is any worse than sorting with nulls in a homogeneous collection. And even in a homogeneous collection, there's no requirement that the individual records be well-typed. I think you couldn't really build that into the spec without saying a lot about type systems, so the spec is agnostic. I can't think of any problems with treating missing fields as null in the sort order.

Regarding filtering, the spec doesn't say much other than that the "filter" query parameter is reserved for filtering. That is deliberate, because different backends could have radically different capabilities and attempting to make a unified query language that is implementable everywhere is a hard problem.

I see a few options, any of which would work for me:

  1. We could choose to only allow filtering on the base fields (title, status, changed, etc) that are present on every node.
  2. Treat non-present fields as not matching the filter
  3. Treating non-present fields as matching the filter

Options 2 and 3 are aided by the fact that field names are unique across all the bundles, so you don't have the problem of a single field name having a different type in different bundles.

Mostly the choice of semantics comes down to implementation complexity. I suspect that option 1 is not a big stretch, but you folks would know better than me.

wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented

Thanks, that's very helpful!

Option 1 would indeed be trivial.

e0ipso’s picture

e0ipso
Primary language Catalan
Location Can Picafort
commented
Status: Active » Closed (won't fix)

There as a somewhat lengthy debate about supporting or not collections that are not bundle specific. We decided not to do it in #2751985: [FEATURE] Add a bundle level relationship to entity level resources.

Since we love the transparency of open source communities, this is the meeting archive when we reached the agreement https://www.youtube.com/watch?v=mveQFnm8S1E

You could probably benefit from https://www.drupal.org/project/subrequests to make those parallel requests and blend the response items together in the client code. All that would still happen in a single request.

Feel free to reopen if necessary.

dawehner’s picture

dawehner
Primary language German
commented

While having some discussion with @justafish I found https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/... which has support for oneOf, so at least from the schema point of view it could be possible.

Client side parsing would of course be needed here, but I think they could deal with that. At least elm can :P

Note: I am not 100% sure whether this belongs into jsonapi itself, maybe jsonapi extras or a submodule there, is the better place for such a feature.