JSON:API has a feature called "fancy filters." These filters let a consumer create complex and powerful queries against a site's content. This feature is built atop Drupal core's Entity Query API.
JSON:API also formats its entity representations to be compliant with the JSON:API spec, for example, the uuid field on every entity is mapped to id in the JSON API response. Where a field only has one property (like a the title field), JSON:API does not output {title: value: "foo"} it simply outputs {title: "foo"}. However, when a field has more than one property, you must specify which property to filter by. For example, a text field now must have a property in the filter path, meaning body would become body.value because body fields have the additional properties format and processed. This matches JSON:API's output, notice how title does not have any child properties, but body does:
{
"attributes": {
"title": "Foo bar baz",
"body": {
"value": "<p>Some body text.</p>\r\n",
"format": "basic_html",
"processed": "<p>Some body text.</p>",
"summary": ""
}
}
}
Filter paths are intended to match the JSON:API output, but because they are built atop the entity query API, it was possible for the internal structure of Drupal's entities to leak through filter paths. As of this change, all filter paths match the JSON:API document structure! No more Drupal-specific surprises.
Some filters which previously worked, may not work any longer.
Examples:
Before After
uuid ==> id
title.value ==> title
field_text ==> field_text.value
field_example.uuid ==> field_example.id
field_image.alt ==> field_image.meta.alt
When upgrading your existing filters, most, if not all, of these changes come with useful error messages that suggest the correct filter path to use. Don't hesitate to just try your existing filters, it is likely that the the resulting error messages will tell you exactly how to correct them.
