-
Notifications
You must be signed in to change notification settings - Fork 890
Description
The 1.1 spec says:
A “query parameter family” is the set of all query parameters whose name starts with a “base name”, followed by zero or more instances of empty square brackets (i.e. []) or square-bracketed legal member names. The family is referred to by its base name.
(Emphasis mine.)
It also says (like 1.0 did) that period .
is a reserved character that may not be used in member names.
Finally, it reserves the filter
query parameter family for filtering data (which is effectively what 1.0 also did).
This then (hopefully accidentally) disallows e.g. filter[author.name]
, since author.name
is not an allowed member name. However, that syntax is a very useful way of filtering on values in related resources (for details, see #1445). Indeed, it is even in line with recommendations for sorting:
Note: It is recommended that dot-separated (U+002E FULL-STOP, “.”) sort fields be used to request sorting based upon relationship attributes. For example, a sort field of
author.name
could be used to request that the primary data be sorted based upon thename
attribute of theauthor
relationship.
Furthermore, it can also be considered a breaking change. The 1.0 spec was not clear about query parameters vs. families, and there was nothing in it that said that constraints were placed on the values in brackets. (An alternative interpretation is that any non-a-z
character made it OK to use the query parameter, which would include [
and ]
, and therefore no query parameter families could be reserved. This seems so wrong I assume that is not a correct interpretation.)
Finally: We use filters like filter[relationshipName.fieldName]
extensively in our APIs, and there is no chance we can change that (or that the JSON:API framework Felicity will enforce disallowing .
in []
in query parameters). So if this is actually an intended part of the spec, this implementation and a host of APIs will be indefinitely non-compliant in this regard.
I assume and hope this is just an oversight. Feel free to clarify if not.