Problem/Motivation

#2725725: [FEATURE] Add support for filtering collections and #2730513: [FEATURE] Add filter syntax shortcut define our filtering strategies and interactions. These are not properly documented anywhere. We should create proper documentation for them so:

  • Developers can understand how to make queries to the Drupal server (DX).
  • Other projects can re-use the filtering strategy, thus making it more stable and reliable.

Proposed resolution

Write the documentation as a JSON API extension and have Drupal support it out of the box.

NOTE: JSON API extensions have been under maintenance for a long while. We can probably write the documentation first and re-format it as a JSON API extension later on.

Remaining tasks

  • Decide where this documentation page should live: GitHub gist, d.o handbook page, this issue queue, …
  • Decide what to call the extension. Note that there may be other filtering strategies out there for JSON API. Also note that if we aspire to other servers to reuse/contribute to this, we may want to leave the word Drupal out of it.

Comments

e0ipso created an issue. See original summary.

e0ipso’s picture

e0ipso
Primary language Catalan
Location Can Picafort
commented

It's worth noting that the existence of #2786945: Examples for more advanced queries. may be proof that we need this, and that we need to have better examples in it.

e0ipso’s picture

e0ipso
Primary language Catalan
Location Can Picafort
commented
Assigned: Unassigned » e0ipso

I will work on this next.

e0ipso’s picture

e0ipso
Primary language Catalan
Location Can Picafort
commented
Status: Active » Needs review

This is the first draft. PRs are welcome: https://gist.github.com/e0ipso/efcc4e96ca2aed58e32948e4f70c2460

gabesullice’s picture

gabesullice
Primary language English
commented

@e0ipso: I've forked and updated your gist. I've just made some minor spelling and grammar adjustments and included/reorganized the complex property ID examples.

You can see the diff here:

https://gist.github.com/gabesullice/5c2a2ab5e29cff30bbae211d6555b513/rev...

gabesullice’s picture

gabesullice
Primary language English
commented

I have a few higher level suggestions:

  • It may be useful to include examples of a response/JSON API representation of a record and then show how one would filter by some of its attributes/relationships
  • The term "Complex property ID" just doesn't feel quite right to me. I think we have too many references to different IDs which makes it confusing. Perhaps just "Property Accessor" and a section for "Property Accessor Format" would be simpler
  • We may want to make support for filtering across relationships an optional requirement. Implementing that is pretty difficult and not strictly necessary in many cases.
  • I think we should specify what operators must be used, IF they are implemented, but perhaps narrow the required subset to just =, <>, >, and <. The grouping operators may present extra implementation challenges. IS NULL and IS NOT NULL may not have meaning for certain API implementations. That is, it may be impossible to have null properties in non-Drupal backends
  • Perhaps we can call them: "complexfilters" instead of "fancyfilters"?
gabesullice’s picture

gabesullice
Primary language English
commented
Status: Needs review » Needs work
gabesullice’s picture

gabesullice
Primary language English
commented
Status: Needs work » Needs review

@e0ipso I've revised my gist according to my suggestions above. I have not added resource examples or changed fancy filters.

I have one more concern:

If the contents of the `memberOf` property does not match any group definition ID, then the conditional object **MAY** be ignored

I'm not sure how we currently handle this, but it's kind of ambiguous. I feel like we should either assign these to the root group or ignore it. But not make it an implementation decision.

e0ipso’s picture

e0ipso
Primary language Catalan
Location Can Picafort
commented
Status: Needs review » Reviewed & tested by the community

https://gist.github.com/e0ipso/efcc4e96ca2aed58e32948e4f70c2460 was updated with the latest changes.

e0ipso’s picture

e0ipso
Primary language Catalan
Location Can Picafort
commented
Status: Reviewed & tested by the community » Fixed

I linked this in the JSON API forums: http://discuss.jsonapi.org/t/share-propose-a-filtering-strategy/257/21?u...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.