Update docs on layer overview and resource definitions.

Author: Bart Koelman

docs/usage/extensibility/layer-overview.md

@@ -1,33 +1,42 @@
 # Layer Overview
 
-By default, data retrieval is distributed across three layers:
+By default, data access flows through the next three layers:
 
 ```
 JsonApiController (required)
+  JsonApiResourceService : IResourceService
+     EntityFrameworkCoreRepository : IResourceRepository
+```
 
-+-- JsonApiResourceService : IResourceService
+Aside from these pluggable endpoint-oriented layers, we provide a resource-oriented extensibility point:
 
-     +-- EntityFrameworkCoreRepository : IResourceRepository
+```
+JsonApiResourceDefinition : IResourceDefinition
 ```
 
-Customization can be done at any of these layers. However, it is recommended that you make your customizations at the service or the repository layer when possible, to keep the controllers free of unnecessary logic.
-You can use the following as a general rule of thumb for where to put business logic:
+Resource definition callbacks are invoked from the built-in resource service/repository layers, as well as from the serializer.
+For example, `IResourceDefinition.OnSerialize` is invoked whenever a resource is sent back to the client, irrespective of the endpoint.
+Likewise, `IResourceDefinition.OnSetToOneRelationshipAsync` is called from a patch-resource-with-relationships endpoint, as well as from patch-relationship.
 
-- `Controller`: simple validation logic that should result in the return of specific HTTP status codes, such as model validation
-- `IResourceService`: advanced business logic and replacement of data access mechanisms
-- `IResourceRepository`: custom logic that builds on the Entity Framework Core APIs
+Customization can be done at any of these extensibility points. It is usually sufficient to place your business logic in a resource definition, but depending
+on your needs, you may want to replace other parts by deriving from the built-in classes and override virtual methods or call their protected base methods.
 
-## Replacing Services
+## Replacing injected services
 
-**Note:** If you are using auto-discovery, resource services and repositories will be automatically registered for you.
+**Note:** If you are using auto-discovery, then resource services, repositories and resource definitions will be automatically registered for you.
 
-Replacing services and repositories is done on a per-resource basis and can be done through dependency injection in your Startup.cs file.
+Replacing built-in services is done on a per-resource basis and can be done through dependency injection in your Startup.cs file.
+For convenience, extension methods are provided to register layers on all their implemented interfaces.
 
 ```c#
 // Startup.cs
 public void ConfigureServices(IServiceCollection services)
 {
-    services.AddScoped<ProductService, IResourceService<Product>();
-    services.AddScoped<ProductRepository, IResourceRepository<Product>>();
+    services.AddResourceService<ProductService>();
+    services.AddResourceRepository<ProductRepository>();
+    services.AddResourceDefinition<ProductDefinition>();
+
+    services.AddScoped<IResourceFactory, CustomResourceFactory>();
+    services.AddScoped<IJsonApiSerializerFactory, CustomResponseSerializerFactory>();
 }
 ```

docs/usage/extensibility/resource-definitions.md

@@ -1,11 +1,19 @@
 # Resource Definitions
 
-In order to improve the developer experience, we have introduced a type that makes
-common modifications to the default API behavior easier. Resource definitions were first introduced in v2.3.4.
+_since v2.3.4_
 
-Resource definitions are resolved from the dependency injection container, so you can inject dependencies in their constructor.
+Resource definitions provide a resource-oriented way to handle custom business logic (irrespective of the originating endpoint).
 
-## Customizing query clauses
+They are resolved from the dependency injection container, so you can inject dependencies in their constructor.
+
+**Note:** Prior to the introduction of auto-discovery (in v3), you needed to register the
+`ResourceDefinition` on the container yourself:
+
+```c#
+services.AddScoped<ResourceDefinition<Product>, ProductResource>();
+```
+
+## Customizing queries
 
 _since v4.0_
 
@@ -21,7 +29,7 @@ from Entity Framework Core `IQueryable` execution.
 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)]`.
+Note: to exclude attributes unconditionally, use `[Attr(Capabilities = ~AttrCapabilities.AllowView)]` on a resource class property.
 
 ```c#
 public class UserDefinition : JsonApiResourceDefinition<User>
@@ -78,7 +86,7 @@ Content-Type: application/vnd.api+json
 }
 ```
 
-## Default sort order
+### Default sort order
 
 You can define the default sort order if no `sort` query string parameter is provided.
 
@@ -106,7 +114,7 @@ public class AccountDefinition : JsonApiResourceDefinition<Account>
 }
 ```
 
-## Enforce page size
+### Enforce page size
 
 You may want to enforce pagination on large database tables.
 
@@ -137,9 +145,9 @@ public class AccessLogDefinition : JsonApiResourceDefinition<AccessLog>
 }
 ```
 
-## Exclude soft-deleted resources
+### Change filters
 
-Soft-deletion sets `IsSoftDeleted` to `true` instead of actually deleting the record, so you may want to always filter them out.
+The next example filters out `Account` resources that are suspended.
 
 ```c#
 public class AccountDefinition : JsonApiResourceDefinition<Account>
@@ -153,23 +161,25 @@ public class AccountDefinition : JsonApiResourceDefinition<Account>
     {
         var resourceContext = ResourceGraph.GetResourceContext<Account>();
 
-        var isSoftDeletedAttribute =
+        var isSuspendedAttribute =
             resourceContext.Attributes.Single(account =>
-                account.Property.Name == nameof(Account.IsSoftDeleted));
+                account.Property.Name == nameof(Account.IsSuspended));
 
-        var isNotSoftDeleted = new ComparisonExpression(ComparisonOperator.Equals,
-            new ResourceFieldChainExpression(isSoftDeletedAttribute),
+        var isNotSuspended = new ComparisonExpression(ComparisonOperator.Equals,
+            new ResourceFieldChainExpression(isSuspendedAttribute),
             new LiteralConstantExpression(bool.FalseString));
 
         return existingFilter == null
-            ? (FilterExpression) isNotSoftDeleted
+            ? (FilterExpression) isNotSuspended
             : new LogicalExpression(LogicalOperator.And,
-                new[] { isNotSoftDeleted, existingFilter });
+                new[] { isNotSuspended, existingFilter });
     }
 }
 ```
 
-## Block including related resources
+### Block including related resources
+
+In the example below, an error is returned when a user tries to include the manager of an employee.
 
 ```c#
 public class EmployeeDefinition : JsonApiResourceDefinition<Employee>
@@ -196,14 +206,14 @@ public class EmployeeDefinition : JsonApiResourceDefinition<Employee>
 }
 ```
 
-## Custom query string parameters
+### Custom query string parameters
 
 _since v3_
 
 You can define additional query string parameters with the LINQ expression that should be used.
 If the key is present in a query string, the supplied LINQ expression will be added to the database query.
 
-Note this directly influences the Entity Framework Core `IQueryable`. As opposed to using `OnApplyFilter`, this enables the full range of EF Core functionality. 
+Note this directly influences the Entity Framework Core `IQueryable`. As opposed to using `OnApplyFilter`, this enables the full range of EF Core operators. 
 But it only works on primary resource endpoints (for example: /articles, but not on /blogs/1/articles or /blogs?include=articles).
 
 ```c#
@@ -237,12 +247,3 @@ public class ItemDefinition : JsonApiResourceDefinition<Item>
     }
 }
 ```
-
-## Using Resource Definitions prior to v3
-
-Prior to the introduction of auto-discovery, you needed to register the
-`ResourceDefinition` on the container yourself:
-
-```c#
-services.AddScoped<ResourceDefinition<Item>, ItemResource>();
-```

docs/usage/reading/filtering.md

@@ -119,7 +119,7 @@ GET /articles?filter[caption]=tech&filter=expr:equals(caption,'cooking')) HTTP/1
 
 There are multiple ways you can add custom filters:
 
-1. Implementing `IResourceDefinition.OnApplyFilter` (see [here](~/usage/extensibility/resource-definitions.md#exclude-soft-deleted-resources)) and inject `IRequestQueryStringAccessor`, which works at all depths, but filter operations are constrained to what `FilterExpression` provides
+1. Implementing `IResourceDefinition.OnApplyFilter` (see [here](~/usage/extensibility/resource-definitions.md#change-filters)) and inject `IRequestQueryStringAccessor`, which works at all depths, but filter operations are constrained to what `FilterExpression` provides
 2. Implementing `IResourceDefinition.OnRegisterQueryableHandlersForQueryStringParameters` as described [here](~/usage/extensibility/resource-definitions.md#custom-query-string-parameters), which enables the full range of `IQueryable<T>` functionality, but only works on primary endpoints
 3. Add an implementation of `IQueryConstraintProvider` to supply additional `FilterExpression`s, which are combined with existing filters using AND operator
 4. Override `EntityFrameworkCoreRepository.ApplyQueryLayer` to adapt the `IQueryable<T>` expression just before execution

docs/usage/resources/relationships.md

@@ -29,7 +29,7 @@ public class Person : Identifiable
 
 ## HasManyThrough
 
-Currently, Entity Framework Core [does not support](https://github.com/aspnet/EntityFrameworkCore/issues/1368) many-to-many relationships without a join entity.
+Earlier versions of Entity Framework Core (up to v5) [did not support](https://github.com/aspnet/EntityFrameworkCore/issues/1368) many-to-many relationships without a join entity.
 For this reason, we have decided to fill this gap by allowing applications to declare a relationship as `HasManyThrough`.
 JsonApiDotNetCore will expose this relationship to the client the same way as any other `HasMany` attribute.
 However, under the covers it will use the join type and Entity Framework Core's APIs to get and set the relationship.