Document advanced use cases

Author: bkoelman

README.md

@@ -256,7 +256,7 @@ To build the code from this repository locally, run:
 dotnet build
 ```
 
-Running tests locally requires access to a PostgreSQL database. If you have docker installed, this can started via:
+Running tests locally requires access to a PostgreSQL database. If you have docker installed, this can be started via:
 
 ```bash
 pwsh run-docker-postgres.ps1

docs/getting-started/faq.md

@@ -11,14 +11,14 @@ The [OpenAPI support in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/c
 and doesn't provide the level of extensibility needed for JsonApiDotNetCore.
 
 #### What's available to implement a JSON:API client?
-It depends on the programming language used. There's an overwhelming list of client libraries at https://jsonapi.org/implementations/#client-libraries.
+To generate a typed client (specific to the resource types in your project), consider using our [OpenAPI](https://www.jsonapi.net/usage/openapi.html) NuGet package.
+
+If you need a generic client, it depends on the programming language used. There's an overwhelming list of client libraries at https://jsonapi.org/implementations/#client-libraries.
 
 The JSON object model inside JsonApiDotNetCore is tweaked for server-side handling (be tolerant at inputs and strict at outputs).
-While you technically *could* use our `JsonSerializer` converters from a .NET client application with some hacks, we don't recommend it.
+While you technically *could* use our `JsonSerializer` converters from a .NET client application with some hacks, we don't recommend doing so.
 You'll need to build the resource graph on the client and rely on internal implementation details that are subject to change in future versions.
 
-In the long term, we'd like to solve this through OpenAPI, which enables the generation of a (statically typed) client library in various languages.
-
 #### How can I debug my API project?
 Due to auto-generated controllers, you may find it hard to determine where to put your breakpoints.
 In Visual Studio, controllers are accessible below **Solution Explorer > Project > Dependencies > Analyzers > JsonApiDotNetCore.SourceGenerators**.

docs/request-examples/index.md

@@ -2,17 +2,18 @@
 
 Runnable example projects can be found [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples):
 
-- GettingStarted: A simple project with minimal configuration to have a runnable project in minutes.
+- GettingStarted: A simple project with minimal configuration to develop a runnable project in minutes.
 - JsonApiDotNetCoreExample: Showcases commonly-used features, such as resource definitions, atomic operations, and OpenAPI.
   - OpenApiNSwagClientExample: Uses [NSwag](https://github.com/RicoSuter/NSwag) to generate a typed OpenAPI client.
   - OpenApiKiotaClientExample: Uses [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/) to generate a typed OpenAPI client.
 - MultiDbContextExample: Shows how to use multiple `DbContext` classes, for connecting to multiple databases.
-- DatabasePerTenantExample: Uses a different database per tenant. See [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/MultiTenancy) for using multiple tenants in the same database.
-- NoEntityFrameworkExample: Uses a read-only in-memory repository instead of a real database.
+- DatabasePerTenantExample: Uses a different database per tenant. See [here](~/usage/advanced/multi-tenancy.md) for using multiple tenants in the same database.
+- NoEntityFrameworkExample: Uses a read-only in-memory repository, instead of a real database.
 - DapperExample: Uses [Dapper](https://github.com/DapperLib/Dapper) to execute SQL queries.
 - ReportsExample: Uses a resource service that returns aggregated data.
 
-Additional use cases are provided as integration tests [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests).
+> [!NOTE]
+> The example projects only cover highly-requested features. More advanced use cases can be found [here](~/usage/advanced/index.md).
 
 # Example requests
 

docs/usage/advanced/alternate-routes.md

@@ -0,0 +1,8 @@
+# Alternate Routes
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/CustomRoutes) shows how the default JSON:API routes can be changed.
+
+The classes `TownsController` and `CiviliansController`:
+- Are decorated with `[DisableRoutingConvention]` to turn off the default JSON:API routing convention.
+- Are decorated with the ASP.NET `[Route]` attribute to specify at which route the controller is exposed.
+- Are augmented with non-standard JSON:API action methods, whose `[HttpGet]` attributes specify a custom route.

docs/usage/advanced/archiving.md

@@ -0,0 +1,14 @@
+# Archiving
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/Archiving) demonstrates how to implement archived resources.
+
+> [!TIP]
+> This scenario is comparable with [Soft Deletion](~/usage/advanced/soft-deletion.md).
+> The difference is that archived resources are accessible to JSON:API clients, whereas soft-deleted resources _never_ are.
+
+- Archived resources can be fetched by ID, but don't show up in searches by default.
+- Resources can only be created in a non-archived state and then archived/unarchived using a PATCH resource request.
+- The archive date is stored in the database, but cannot be modified through JSON:API.
+- To delete a resource, it must be archived first.
+
+This feature is implemented using a custom resource definition. It intercepts write operations and recursively scans incoming filters.

docs/usage/advanced/auth-scopes.md

@@ -0,0 +1,10 @@
+# Authorization Scopes
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/Authorization/Scopes) shows how scope-based authorization can be used.
+
+- For simplicity, this code assumes the granted scopes are passed in a plain-text HTTP header. A more realistic use case would be to obtain the scopes from an OAuth token.
+- The HTTP header lists which resource types can be read from and/or written to.
+- An [ASP.NET Action Filter](https://learn.microsoft.com/aspnet/core/mvc/controllers/filters) validates incoming JSON:API resource/relationship requests.
+  - The incoming request path is validated against the permitted read/write permissions per resource type.
+  - The resource types used in query string parameters are validated against the permitted set of resource types.
+- A customized operations controller verifies that all incoming operations are allowed.

docs/usage/advanced/blobs.md

@@ -0,0 +1,9 @@
+# BLOBs
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/Blobs) shows how Binary Large Objects (BLOBs) can be used.
+
+- The `ImageContainer` resource type contains nullable and non-nullable `byte[]` properties.
+- BLOBs are queried and persisted using Entity Framework Core.
+- The BLOB data is returned as a base-64 encoded string in the JSON response.
+
+Blobs are handled automatically; there's no need for custom code.

docs/usage/advanced/composite-keys.md

@@ -0,0 +1,8 @@
+# Composite Keys
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/CompositeKeys) shows how database tables with composite keys can be used.
+
+- The `DbContext` configures `Car` to have a composite primary key consisting of the `RegionId` and `LicensePlate` columns.
+- The `Car.Id` property is overridden to provide a unique ID for JSON:API. It is marked with `[NotMapped]`, meaning no `Id` column exists in the database table.
+- The `Engine` and `Dealership` resource types define relationships that generate composite foreign keys in the database.
+- A custom resource repository is used to rewrite IDs from filter/sort query string parameters into `RegionId` and `LicensePlate` lookups.

docs/usage/advanced/content-negotiation.md

@@ -0,0 +1,15 @@
+# Content Negotiation
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/ContentNegotiation) demonstrates how content negotiation in JSON:API works.
+
+Additionally, the code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/ContentNegotiation/CustomExtensions) provides
+a custom "server-time" JSON:API extension that returns the local or UTC server time in top-level `meta`.
+- This extension can be used in the `Accept` and `Content-Type` HTTP headers.
+- In a request body, the optional `useLocalTime` property in top-level `meta` indicates whether to return the local or UTC time.
+
+This feature is implemented using the following extensibility points:
+
+- At startup, the "server-time" extension is added in `JsonApiOptions`, which permits clients to use it.
+- A custom `JsonApiContentNegotiator` chooses which extensions are active for an incoming request, taking the "server-time" extension into account.
+- A custom `IDocumentAdapter` captures the incoming request body, providing access to the `useLocalTime` property in `meta`.
+- A custom `IResponseMeta` adds the server time to the response, depending on the activated extensions in `IJsonApiRequest` and the captured request body.

docs/usage/advanced/eager-loading.md

@@ -0,0 +1,12 @@
+# Eager Loading Related Resources
+
+The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/EagerLoading) uses the `[EagerLoad]` attribute to facilitate calculated properties that depend on related resources.
+The related resources are fetched from the database, but not returned to the client unless explicitly requested using the `include` query string parameter.
+
+- The `Street` resource type uses `EagerLoad` on its `Buildings` to-many relationship because its `DoorTotalCount` calculated property depends on it.
+- The `Building` resource type uses `EagerLoad` on its `Windows` to-many relationship because its `WindowCount` calculated property depends on it.
+- The `Building` resource type uses `EagerLoad` on its `PrimaryDoor` to-one required relationship because its `PrimaryDoorColor` calculated property depends on it.
+  - Because this is a required relationship, special handling occurs in `Building`, `BuildingRepository`, and `BuildingDefinition`.
+- The `Building` resource type uses `EagerLoad` on its `SecondaryDoor` to-one optional relationship because its `SecondaryDoorColor` calculated property depends on it.
+
+As can be seen from the usages above, a chain of `EagerLoad` attributes can result in fetching a chain of related resources from the database.