Changes usage of fields parameter to be json:api spec compliant (#904)

* Changes the use of fields query string parameter to be json:api spec compliant.

Before we'd accept a relationship path between the square brackets and would only allow attribute names in the value. Now we expect a resource type between square brackets and the value can contain both attributes and relationships.

* Fixed: pass ID attribute in ResourceDefinition callback for relationships.

Author: Bart Koelman

benchmarks/Query/QueryParserBenchmarks.cs

@@ -31,7 +31,8 @@ public QueryParserBenchmarks()
 
             var request = new JsonApiRequest
             {
-                PrimaryResource = resourceGraph.GetResourceContext(typeof(BenchmarkResource))
+                PrimaryResource = resourceGraph.GetResourceContext(typeof(BenchmarkResource)),
+                IsCollection = true
             };
 
             _queryStringReaderForSort = CreateQueryParameterDiscoveryForSort(resourceGraph, request, options, _queryStringAccessor);
@@ -56,6 +57,7 @@ private static QueryStringReader CreateQueryParameterDiscoveryForAll(IResourceGr
         {
             var resourceFactory = new ResourceFactory(new ServiceContainer());
 
+            var includeReader = new IncludeQueryStringParameterReader(request, resourceGraph, options);
             var filterReader = new FilterQueryStringParameterReader(request, resourceGraph, resourceFactory, options);
             var sortReader = new SortQueryStringParameterReader(request, resourceGraph);
             var sparseFieldSetReader = new SparseFieldSetQueryStringParameterReader(request, resourceGraph);
@@ -65,7 +67,7 @@ private static QueryStringReader CreateQueryParameterDiscoveryForAll(IResourceGr
 
             var readers = new List<IQueryStringParameterReader>
             {
-                filterReader, sortReader, sparseFieldSetReader, paginationReader, defaultsReader, nullsReader
+                includeReader, filterReader, sortReader, sparseFieldSetReader, paginationReader, defaultsReader, nullsReader
             };
 
             return new QueryStringReader(options, queryStringAccessor, readers, NullLoggerFactory.Instance);
@@ -92,7 +94,7 @@ public void DescendingSort()
         [Benchmark]
         public void ComplexQuery() => Run(100, () =>
         {
-            var queryString = $"?filter[{BenchmarkResourcePublicNames.NameAttr}]=abc,eq:abc&sort=-{BenchmarkResourcePublicNames.NameAttr}&include=child&page[size]=1&fields={BenchmarkResourcePublicNames.NameAttr}";
+            var queryString = $"?filter[{BenchmarkResourcePublicNames.NameAttr}]=abc,eq:abc&sort=-{BenchmarkResourcePublicNames.NameAttr}&include=child&page[size]=1&fields[{BenchmarkResourcePublicNames.Type}]={BenchmarkResourcePublicNames.NameAttr}";
 
             _queryStringAccessor.SetQueryString(queryString);
             _queryStringReaderForAll.ReadAll(null);

docs/internals/queries.md

@@ -34,13 +34,13 @@ To get a sense of what this all looks like, let's look at an example query strin
   filter=has(articles)&
   sort=count(articles)&
   page[number]=3&
-  fields=title&
+  fields[blogs]=title&
     filter[articles]=and(not(equals(author.firstName,null)),has(revisions))&
     sort[articles]=author.lastName&
     fields[articles]=url&
       filter[articles.revisions]=and(greaterThan(publishTime,'2001-01-01'),startsWith(author.firstName,'J'))&
       sort[articles.revisions]=-publishTime,author.lastName&
-      fields[articles.revisions]=publishTime
+      fields[revisions]=publishTime
 ```
 
 After parsing, the set of scoped expressions is transformed into the following tree by `QueryLayerComposer`:

docs/request-examples/004_GET_Books-PublishYear.ps1

@@ -1 +1 @@
-curl -s -f http://localhost:14141/api/books?fields=publishYear
+curl -s -f http://localhost:14141/api/books?fields%5Bbooks%5D=publishYear

docs/usage/reading/sparse-fieldset-selection.md

@@ -1,21 +1,24 @@
 # Sparse Fieldset Selection
 
-As an alternative to returning all attributes from a resource, the `fields` query string parameter can be used to select only a subset.
-This can be used on the resource being requested, as well as nested endpoints and/or included resources.
+As an alternative to returning all fields (attributes and relationships) from a resource, the `fields[]` query string parameter can be used to select a subset.
+Put the resource type to apply the fieldset on between the brackets.
+This can be used on the resource being requested, as well as on nested endpoints and/or included resources.
 
 Top-level example:
 ```http
-GET /articles?fields=title,body HTTP/1.1
+GET /articles?fields[articles]=title,body,comments HTTP/1.1
 ```
 
 Nested endpoint example:
 ```http
-GET /api/blogs/1/articles?fields=title,body HTTP/1.1
+GET /api/blogs/1/articles?fields[articles]=title,body,comments HTTP/1.1
 ```
 
+When combined with the `include` query string parameter, a subset of related fields can be specified too.
+
 Example for an included HasOne relationship:
 ```http
-GET /articles?include=author&fields[author]=name HTTP/1.1
+GET /articles?include=author&fields[authors]=name HTTP/1.1
 ```
 
 Example for an included HasMany relationship:
@@ -25,9 +28,12 @@ GET /articles?include=revisions&fields[revisions]=publishTime HTTP/1.1
 
 Example for both top-level and relationship:
 ```http
-GET /articles?include=author&fields=title,body&fields[author]=name HTTP/1.1
+GET /articles?include=author&fields[articles]=title,body,author&fields[authors]=name HTTP/1.1
 ```
 
+Note that in the last example, the `author` relationship is also added to the `articles` fieldset, so that the relationship from article to author is returned.
+When omitted, you'll get the included resources returned, but without full resource linkage (as described [here](https://jsonapi.org/examples/#sparse-fieldsets)).
+
 ## Overriding
 
 As a developer, you can force to include and/or exclude specific fields as [described previously](~/usage/resources/resource-definitions.md).

docs/usage/resources/attributes.md

@@ -39,7 +39,7 @@ This can be overridden per attribute.
 
 ### Viewability
 
-Attributes can be marked to allow returning their value in responses. When not allowed and requested using `?fields=`, it results in an HTTP 400 response.
+Attributes can be marked to allow returning their value in responses. When not allowed and requested using `?fields[]=`, it results in an HTTP 400 response.
 
 ```c#
 public class User : Identifiable

docs/usage/resources/resource-definitions.md

@@ -18,7 +18,7 @@ from Entity Framework Core `IQueryable` execution.
 
 ### Excluding fields
 
-There are some cases where you want attributes conditionally excluded from your resource response.
+There are some cases where you want attributes (or relationships) conditionally excluded from your resource response.
 For example, you may accept some sensitive data that should only be exposed to administrators after creation.
 
 Note: to exclude attributes unconditionally, use `[Attr(Capabilities = ~AttrCapabilities.AllowView)]`.

docs/usage/writing/creating.md

@@ -61,10 +61,10 @@ POST /articles HTTP/1.1
 
 # Response body
 
-POST requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields`. For example:
+POST requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields[]`. For example:
 
 ```http
-POST /articles?include=owner&fields[owner]=firstName HTTP/1.1
+POST /articles?include=owner&fields[people]=firstName HTTP/1.1
 
 {
   ...

docs/usage/writing/updating.md

@@ -69,10 +69,10 @@ By combining the examples above, both attributes and relationships can be update
 
 ## Response body
 
-PATCH requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields`. For example:
+PATCH requests can be combined with query string parameters that are normally used for reading data, such as `include` and `fields[]`. For example:
 
 ```http
-PATCH /articles/1?include=owner&fields[owner]=firstName HTTP/1.1
+PATCH /articles/1?include=owner&fields[people]=firstName HTTP/1.1
 
 {
   ...

src/Examples/JsonApiDotNetCoreExample/Models/Passport.cs

@@ -1,7 +1,5 @@
 using System;
-using System.Collections.Generic;
 using System.ComponentModel.DataAnnotations.Schema;
-using System.Linq;
 using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Resources.Annotations;
 using JsonApiDotNetCoreExample.Data;

src/JsonApiDotNetCore/Errors/ResourcesInRelationshipsNotFoundException.cs

@@ -1,4 +1,3 @@
-using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Net;