Various fixes and improvements (#1114)

* Fixed inconsistencies in naming of resource type

* Fixed: Query to determine initial state is sent to the read-only database on POST many-to-many and DELETE to-many requests

* Make command/query controllers inherit from JsonApiController, passing null for missing services
This produces HTTP 405 (Method Not Allowed) instead of 404 (Not Found), which better reveals the intent

* Added overload on TypeExtensions.IsOrImplementsInterface to take a type parameter, used for non-generic or generic constructed interfaces

* Use ResourceType instead of public name in local-id tracker

* Change IQueryStringParameterReader.AllowEmptyValue into normal interface member

* Simplified startup in example project

* Removed left-over overload with single type parameter in ResourceGraphBuilder

* Various corrections in documentation, added #nullable where it makes a difference

* Revert DocFx workaround

* Updated version compatibility table

* Added release notes and icon to NuGet package

* Fix nullability warnings produced by .NET 6 with EF Core 6

* Fixed: Error when using EagerLoad on a relationship

* Use VS2022 image in AppVeyor on Windows

* Fixed broken tests on EF Core 6
Apparently EF Core 5 did not always fail on missing required relationships, which was fixed in EF Core 6. I tried to update existing tests leaving the models intact, but that poluted lots of tests so I made them optional instead.

* Fixed redacted data when running tests

* Breaking: Removed access-control action filter attributes such as HttpReadOnly, NoHttpPost etc. because they interfere with relationship endpoints. For example, blocking POST would block creating resources, as well as adding to to-many relationships, which is not very useful. The replacement is to inject just the subset of exposed services, or simply use the Command/Query controllers. When an endpoint is not exposed, we now return HTTP 403 Forbidden instead of 404 or 405.

* Increase version number, use branch name in suffix

* Pass the full resource to LinkBuilder, instead of just its ID. This allows for more intelligence in the link builder, such as handling versioning or inheritance.

* Optimization: Only save when there are changes in a remove-from-to-many relationship request

* Clarifications in doc-comments

* Extract constant

* Extract method

* Cleanup SelectClauseBuilder.ToPropertySelectors

* Since EF Core 5, SaveChanges automatically creates a savepoint and rolls back to it on failure. This produces more correct error responses in operations, compared to rolling back the entire transaction. For example, when an operations request creates a resource and the next operation fails, the resource service may incorrectly conclude that the resource from the first operation does not exist.

* Improved unittests for populating IJsonApiRequest in middleware

* Clarify intent in AtomicOperationObjectAdapter

* Review feedback: use `ResourceType resourceType` instead of `ResourceType type` everywhere

Author: Bart Koelman

Build.ps1

@@ -73,10 +73,10 @@ function CreateNuGetPackage {
         $versionSuffix = $suffixSegments -join "-"
     }
     else {
-        # Get the version suffix from the auto-incrementing build number. Example: "123" => "pre-0123".
+        # Get the version suffix from the auto-incrementing build number. Example: "123" => "master-0123".
         if ($env:APPVEYOR_BUILD_NUMBER) {
             $revision = "{0:D4}" -f [convert]::ToInt32($env:APPVEYOR_BUILD_NUMBER, 10)
-            $versionSuffix = "pre-$revision"
+            $versionSuffix = "$($env:APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH ?? $env:APPVEYOR_REPO_BRANCH)-$revision"
         }
         else {
             $versionSuffix = "pre-0001"

README.md

@@ -43,21 +43,23 @@ See [our documentation](https://www.jsonapi.net/) for detailed usage.
 ### Models
 
 ```c#
-public class Article : Identifiable
+#nullable enable
+
+public class Article : Identifiable<int>
 {
     [Attr]
-    public string Name { get; set; }
+    public string Name { get; set; } = null!;
 }
 ```
 
 ### Controllers
 
 ```c#
-public class ArticlesController : JsonApiController<Article>
+public class ArticlesController : JsonApiController<Article, int>
 {
-    public ArticlesController(IJsonApiOptions options, ILoggerFactory loggerFactory,
-        IResourceService<Article> resourceService,)
-        : base(options, loggerFactory, resourceService)
+    public ArticlesController(IJsonApiOptions options, IResourceGraph resourceGraph,
+        ILoggerFactory loggerFactory, IResourceService<Article, int> resourceService)
+        : base(options, resourceGraph, loggerFactory, resourceService)
     {
     }
 }
@@ -87,13 +89,16 @@ public class Startup
 The following chart should help you pick the best version, based on your environment.
 See also our [versioning policy](./VERSIONING_POLICY.md).
 
-| .NET version | Entity Framework Core version | JsonApiDotNetCore version |
-| ------------ | ----------------------------- | ------------------------- |
-| Core 2.x     | 2.x                           | 3.x                       |
-| Core 3.1     | 3.1                           | 4.x                       |
-| Core 3.1     | 5                             | 4.x                       |
-| 5            | 5                             | 4.x or 5.x                |
-| 6            | 6                             | 5.x                       |
+| JsonApiDotNetCore | .NET     | Entity Framework Core | Status                     |
+| ----------------- | -------- | --------------------- | -------------------------- |
+| 3.x               | Core 2.x | 2.x                   | Released                   |
+| 4.x               | Core 3.1 | 3.1                   | Released                   |
+|                   | Core 3.1 | 5                     |                            |
+|                   | 5        | 5                     |                            |
+|                   | 6        | 5                     |                            |
+| v5.x (pending)    | 5        | 5                     | On AppVeyor, to-be-dropped |
+|                   | 6        | 5                     | On AppVeyor, to-be-dropped |
+|                   | 6        | 6                     | Requires build from master |
 
 ## Contributing
 

appveyor.yml

@@ -1,6 +1,6 @@
 image:
   - Ubuntu
-  - Visual Studio 2019
+  - Visual Studio 2022
 
 version: '{build}'
 
@@ -32,7 +32,7 @@ for:
 -
   matrix:
     only:
-    - image: Visual Studio 2019
+    - image: Visual Studio 2022
   services:
   - postgresql13
   # REF: https://github.com/docascode/docfx-seed/blob/master/appveyor.yml
@@ -42,9 +42,7 @@ for:
             # https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
             git checkout $env:APPVEYOR_REPO_BRANCH -q
         }
-        # Pinning to previous version, because zip of v2.58.8 (released 2d ago) is corrupt.
-        # Tracked at https://github.com/dotnet/docfx/issues/7689
-        choco install docfx -y --version 2.58.5
+        choco install docfx -y
         if ($lastexitcode -ne 0) {
             throw "docfx install failed with exit code $lastexitcode."
         }

benchmarks/Deserialization/DeserializationBenchmarkBase.cs

@@ -21,7 +21,7 @@ public abstract class DeserializationBenchmarkBase
         protected DeserializationBenchmarkBase()
         {
             var options = new JsonApiOptions();
-            IResourceGraph resourceGraph = new ResourceGraphBuilder(options, NullLoggerFactory.Instance).Add<IncomingResource>().Build();
+            IResourceGraph resourceGraph = new ResourceGraphBuilder(options, NullLoggerFactory.Instance).Add<IncomingResource, int>().Build();
             options.SerializerOptions.Converters.Add(new ResourceObjectConverter(resourceGraph));
             SerializerReadOptions = ((IJsonApiOptions)options).SerializerReadOptions;
 

benchmarks/QueryString/QueryStringParserBenchmarks.cs

@@ -29,7 +29,8 @@ public QueryStringParserBenchmarks()
                 EnableLegacyFilterNotation = true
             };
 
-            IResourceGraph resourceGraph = new ResourceGraphBuilder(options, NullLoggerFactory.Instance).Add<QueryableResource>("alt-resource-name").Build();
+            IResourceGraph resourceGraph =
+                new ResourceGraphBuilder(options, NullLoggerFactory.Instance).Add<QueryableResource, int>("alt-resource-name").Build();
 
             var request = new JsonApiRequest
             {

benchmarks/Serialization/SerializationBenchmarkBase.cs

@@ -40,7 +40,7 @@ protected SerializationBenchmarkBase()
                 }
             };
 
-            ResourceGraph = new ResourceGraphBuilder(options, NullLoggerFactory.Instance).Add<OutgoingResource>().Build();
+            ResourceGraph = new ResourceGraphBuilder(options, NullLoggerFactory.Instance).Add<OutgoingResource, int>().Build();
             SerializerWriteOptions = ((IJsonApiOptions)options).SerializerWriteOptions;
 
             // ReSharper disable VirtualMemberCallInConstructor
@@ -229,15 +229,15 @@ public TopLevelLinks GetTopLevelLinks()
                 };
             }
 
-            public ResourceLinks GetResourceLinks(ResourceType resourceType, string id)
+            public ResourceLinks GetResourceLinks(ResourceType resourceType, IIdentifiable resource)
             {
                 return new ResourceLinks
                 {
                     Self = "Resource:Self"
                 };
             }
 
-            public RelationshipLinks GetRelationshipLinks(RelationshipAttribute relationship, string leftId)
+            public RelationshipLinks GetRelationshipLinks(RelationshipAttribute relationship, IIdentifiable leftResource)
             {
                 return new RelationshipLinks
                 {

docs/getting-started/step-by-step.md

@@ -38,10 +38,12 @@ Define your domain models such that they implement `IIdentifiable<TId>`.
 The easiest way to do this is to inherit from `Identifiable<TId>`.
 
 ```c#
+#nullable enable
+
 public class Person : Identifiable<int>
 {
     [Attr]
-    public string Name { get; set; }
+    public string Name { get; set; } = null!;
 }
 ```
 
@@ -52,12 +54,12 @@ Nothing special here, just an ordinary `DbContext`.
 ```
 public class AppDbContext : DbContext
 {
+    public DbSet<Person> People => Set<Person>();
+
     public AppDbContext(DbContextOptions<AppDbContext> options)
         : base(options)
     {
     }
-
-    public DbSet<Person> People { get; set; }
 }
 ```
 

docs/home/index.html

@@ -142,31 +142,35 @@ <h2>Example usage</h2>
                      <div class="icon"><i class='bx bx-detail'></i></div>
                      <h4 class="title">Resource</h4>
                      <pre>
-<code>public class Article : Identifiable
+<code>#nullable enable
+
+public class Article : Identifiable&lt;long&gt;
 {
     [Attr]
-    [Required, MaxLength(30)]
-    public string Title { get; set; }
+    [MaxLength(30)]
+    public string Title { get; set; } = null!;
 
     [Attr(Capabilities = AttrCapabilities.AllowFilter)]
-    public string Summary { get; set; }
+    public string? Summary { get; set; }
 
     [Attr(PublicName = "websiteUrl")]
-    public string Url { get; set; }
+    public string? Url { get; set; }
+
+    [Attr]
+    [Required]
+    public int? WordCount { get; set; }
 
     [Attr(Capabilities = AttrCapabilities.AllowView)]
     public DateTimeOffset LastModifiedAt { get; set; }
 
     [HasOne]
-    public Person Author { get; set; }
+    public Person Author { get; set; } = null!;
 
-    [HasMany]
-    public ICollection&lt;Revision&gt; Revisions { get; set; }  
+    [HasOne]
+    public Person? Reviewer { get; set; }
 
-    [HasManyThrough(nameof(ArticleTags))]
-    [NotMapped]
-    public ICollection&lt;Tag&gt; Tags { get; set; }
-    public ICollection&lt;ArticleTag&gt; ArticleTags { get; set; }
+    [HasMany]
+    public ICollection&lt;Tag&gt; Tags { get; set; } = new HashSet&lt;Tag&gt;();
 }</code>
                      </pre>
                   </div>
@@ -179,7 +183,7 @@ <h4 class="title">Resource</h4>
                      <h4 class="title">Request</h4>
                      <pre>
 <code>
-GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author HTTP/1.1
+GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields[articles]=title,summary&include=author HTTP/1.1
 </code>
                      </pre>
                   </div>
@@ -197,9 +201,9 @@ <h4 class="title">Response</h4>
     "totalResources": 1
   },
   "links": {
-    "self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author",
-    "first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author",
-    "last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author"
+    "self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
+    "first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
+    "last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author"
   },
   "data": [
     {

docs/usage/errors.md

@@ -10,7 +10,7 @@ From a controller method:
 return Conflict(new Error(HttpStatusCode.Conflict)
 {
     Title = "Target resource was modified by another user.",
-    Detail = $"User {userName} changed the {resourceField} field on the {resourceName} resource."
+    Detail = $"User {userName} changed the {resourceField} field on {resourceName} resource."
 });
 ```
 
@@ -20,7 +20,7 @@ From other code:
 throw new JsonApiException(new Error(HttpStatusCode.Conflict)
 {
     Title = "Target resource was modified by another user.",
-    Detail = $"User {userName} changed the {resourceField} field on the {resourceName} resource."
+    Detail = $"User {userName} changed the {resourceField} field on {resourceName} resource."
 });
 ```
 
@@ -69,18 +69,22 @@ public class CustomExceptionHandler : ExceptionHandler
         return base.GetLogMessage(exception);
     }
 
-    protected override ErrorDocument CreateErrorDocument(Exception exception)
+    protected override IReadOnlyList<ErrorObject> CreateErrorResponse(Exception exception)
     {
         if (exception is ProductOutOfStockException productOutOfStock)
         {
-            return new ErrorDocument(new Error(HttpStatusCode.Conflict)
+            return new[]
             {
-                Title = "Product is temporarily available.",
-                Detail = $"Product {productOutOfStock.ProductId} cannot be ordered at the moment."
-            });
+                new Error(HttpStatusCode.Conflict)
+                {
+                    Title = "Product is temporarily available.",
+                    Detail = $"Product {productOutOfStock.ProductId} " +
+                        "cannot be ordered at the moment."
+                }
+            };
         }
 
-        return base.CreateErrorDocument(exception);
+        return base.CreateErrorResponse(exception);
     }
 }
 

docs/usage/extensibility/controllers.md

@@ -13,83 +13,49 @@ public class ArticlesController : JsonApiController<Article, Guid>
 }
 ```
 
+If you want to setup routes yourself, you can instead inherit from `BaseJsonApiController<TResource, TId>` and override its methods with your own `[HttpGet]`, `[HttpHead]`, `[HttpPost]`, `[HttpPatch]` and `[HttpDelete]` attributes added on them. Don't forget to add `[FromBody]` on parameters where needed.
+
 ## Resource Access Control
 
-It is often desirable to limit what methods are exposed on your controller. The first way you can do this, is to simply inherit from `BaseJsonApiController` and explicitly declare what methods are available.
+It is often desirable to limit which routes are exposed on your controller.
 
-In this example, if a client attempts to do anything other than GET a resource, an HTTP 404 Not Found response will be returned since no other methods are exposed.
+To provide read-only access, inherit from `JsonApiQueryController` instead, which blocks all POST, PATCH and DELETE requests.
+Likewise, to provide write-only access, inherit from `JsonApiCommandController`, which blocks all GET and HEAD requests.
 
-This approach is ok, but introduces some boilerplate that can easily be avoided.
+You can even make your own mix of allowed routes by calling the alternate constructor of `JsonApiController` and injecting the set of service implementations available.
+In some cases, resources may be an aggregation of entities or a view on top of the underlying entities. In these cases, there may not be a writable `IResourceService` implementation, so simply inject the implementation that is available.
 
 ```c#
-public class ArticlesController : BaseJsonApiController<Article, int>
+public class ReportsController : JsonApiController<Report, int>
 {
-    public ArticlesController(IJsonApiOptions options, IResourceGraph resourceGraph,
-        ILoggerFactory loggerFactory, IResourceService<Article, int> resourceService)
-        : base(options, resourceGraph, loggerFactory, resourceService)
-    {
-    }
-
-    [HttpGet]
-    public override async Task<IActionResult> GetAsync(CancellationToken cancellationToken)
-    {
-        return await base.GetAsync(cancellationToken);
-    }
-
-    [HttpGet("{id}")]
-    public override async Task<IActionResult> GetAsync(int id,
-        CancellationToken cancellationToken)
+    public ReportsController(IJsonApiOptions options, IResourceGraph resourceGraph,
+        ILoggerFactory loggerFactory, IGetAllService<Report, int> getAllService)
+        : base(options, resourceGraph, loggerFactory, getAll: getAllService)
     {
-        return await base.GetAsync(id, cancellationToken);
     }
 }
 ```
 
-## Using ActionFilterAttributes
-
-The next option is to use the ActionFilter attributes that ship with the library. The available attributes are:
-
-- `NoHttpPost`: disallow POST requests
-- `NoHttpPatch`: disallow PATCH requests
-- `NoHttpDelete`: disallow DELETE requests
-- `HttpReadOnly`: all of the above
+For more information about resource service injection, see [Replacing injected services](~/usage/extensibility/layer-overview.md#replacing-injected-services) and [Resource Services](~/usage/extensibility/services.md).
 
-Not only does this reduce boilerplate, but it also provides a more meaningful HTTP response code.
-An attempt to use one of the blacklisted methods will result in a HTTP 405 Method Not Allowed response.
+When a route is blocked, an HTTP 403 Forbidden response is returned.
 
-```c#
-[HttpReadOnly]
-public class ArticlesController : BaseJsonApiController<Article, int>
-{
-    public ArticlesController(IJsonApiOptions options, IResourceGraph resourceGraph,
-        ILoggerFactory loggerFactory, IResourceService<Article, int> resourceService)
-        : base(options, resourceGraph, loggerFactory, resourceService)
-    {
-    }
-}
+```http
+DELETE http://localhost:14140/people/1 HTTP/1.1
 ```
 
-## Implicit Access By Service Injection
-
-Finally, you can control the allowed methods by supplying only the available service implementations. In some cases, resources may be an aggregation of entities or a view on top of the underlying entities. In these cases, there may not be a writable `IResourceService` implementation, so simply inject the implementation that is available.
-
-As with the ActionFilter attributes, if a service implementation is not available to service a request, HTTP 405 Method Not Allowed will be returned.
-
-For more information about resource service injection, see [Replacing injected services](~/usage/extensibility/layer-overview.md#replacing-injected-services) and [Resource Services](~/usage/extensibility/services.md).
-
-```c#
-public class ReportsController : BaseJsonApiController<Report, int>
+```json
 {
-    public ReportsController(IJsonApiOptions options, IResourceGraph resourceGraph,
-        ILoggerFactory loggerFactory, IGetAllService<Report, int> getAllService)
-        : base(options, resourceGraph, loggerFactory, getAllService)
-    {
-    }
-
-    [HttpGet]
-    public override async Task<IActionResult> GetAsync(CancellationToken cancellationToken)
+  "links": {
+    "self": "/api/v1/people"
+  },
+  "errors": [
     {
-        return await base.GetAsync(cancellationToken);
+      "id": "dde7f219-2274-4473-97ef-baac3e7c1487",
+      "status": "403",
+      "title": "The requested endpoint is not accessible.",
+      "detail": "Endpoint '/people/1' is not accessible for DELETE requests."
     }
+  ]
 }
 ```