Improve support nested sparse field selection

[maurei]

This is the recommendation from the official json:api spec with respect to sparse field selection:

GET /articles?include=author&fields[articles]=title,body&fields[people]=name

There is a serious limitation with this. This is described in json-api/json-api#1091. If article contains two relationships to people, eg a reviewer and an author, then we would not be able to do a unique field selection for either one of them. For that we would need a sparse field query syntax of the form fields[ relationship_navigation ] rather than fields[ related_type ].

We could then do things like

GET /articles?include=author,reviewer.employer
                      &fields[author]=name
                      &fields[reviewer]=age
                      &fields[reviewer.employer]=foundedAt

To support fully support such nested sparse field selection, we would have to switch to the fields[ relationship_navigation ] syntax. It seems that @milosloub already implemented this syntax for 1 level deep relationship inclusions.

Right now the fields[ type ] as well as fields[ relationship_navigation ] syntax is allowed. This is inconsistent and incompatible. What is left to do is disallow the fields[ type ] syntax.

• This means that articles?fields[articles]=title is no longer valid. For field selection of the main request resource I propose to simply use articles?fields=title, no navigation is needed.
• To give users a constructive error we should generate a constructive error message when the case of the previous bulletin occurs
  • fields[articles]=title would give a 400 with a message to just use fields=title
• in the rare case that the main request resource actually has a relationship that is identical to the resource name, we will allow it. This could happen with a nested, circular data structure like directories
  • eg: folders?fields[folders]=isEndNode would still be possible