diff --git a/docs/internals/toc.md b/docs/internals/toc.md deleted file mode 100644 index 0533dc527..000000000 --- a/docs/internals/toc.md +++ /dev/null @@ -1 +0,0 @@ -# [Queries](queries.md) diff --git a/docs/internals/toc.yml b/docs/internals/toc.yml new file mode 100644 index 000000000..adb35afc5 --- /dev/null +++ b/docs/internals/toc.yml @@ -0,0 +1,2 @@ +- name: Queries + href: queries.md diff --git a/docs/request-examples/README.md b/docs/request-examples/README.md index eb95ea465..5a2911f5c 100644 --- a/docs/request-examples/README.md +++ b/docs/request-examples/README.md @@ -2,18 +2,20 @@ To update these requests: -1. Add a PowerShell (.ps1) script prefixed by a number that is used to determine the order the scripts are executed. The script should execute a request and output the response. Example: -``` -curl -s http://localhost:14141/api/books -``` +1. Add a PowerShell (`.ps1`) script prefixed by a number that is used to determine the order the scripts are executed. + The script should execute a request and output the response. For example: + ``` + curl -s http://localhost:14141/api/books + ``` -2. Add the example to `index.md`. Example: -``` -### Get with relationship +2. Add the example to `index.md`. For example: + ``` + ### Get with relationship -[!code-ps[REQUEST](003_GET_Books-including-Author.ps1)] -[!code-json[RESPONSE](003_GET_Books-including-Author_Response.json)] -``` + [!code-ps[REQUEST](003_GET_Books-including-Author.ps1)] + [!code-json[RESPONSE](003_GET_Books-including-Author_Response.json)] + ``` -3. Run `pwsh ../generate-examples.ps1` -4. Verify the results by running `pwsh ../build-dev.ps1` +3. Run `pwsh ../generate-examples.ps1` to execute the request. + +4. Run `pwsh ../build-dev.ps1` to view the output on the website. diff --git a/docs/request-examples/index.md b/docs/request-examples/index.md index 614aa4814..89c704345 100644 --- a/docs/request-examples/index.md +++ b/docs/request-examples/index.md @@ -1,17 +1,28 @@ ---- -_disableToc: true ---- +# Example projects -# Example requests +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 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](~/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. -These requests have been generated against the "GettingStarted" application and are updated on every deployment. +> [!NOTE] +> The example projects only cover highly-requested features. More advanced use cases can be found [here](~/usage/advanced/index.md). + +# Example requests -All of these requests have been created using out-of-the-box features. +The following requests are automatically generated against the "GettingStarted" application on every deployment. > [!NOTE] > curl requires "[" and "]" in URLs to be escaped. -# Reading data +## Reading data ### Get all @@ -48,7 +59,7 @@ All of these requests have been created using out-of-the-box features. [!code-ps[REQUEST](007_GET_Books-paginated.ps1)] [!code-json[RESPONSE](007_GET_Books-paginated_Response.json)] -# Writing data +## Writing data ### Create resource diff --git a/docs/request-examples/toc.md b/docs/request-examples/toc.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/template/public/main.css b/docs/template/public/main.css new file mode 100644 index 000000000..a20926d93 --- /dev/null +++ b/docs/template/public/main.css @@ -0,0 +1,6 @@ +/* From https://github.com/dotnet/docfx/discussions/9644 */ + +body { + --bs-link-color-rgb: 66, 184, 131 !important; + --bs-link-hover-color-rgb: 64, 180, 128 !important; +} diff --git a/docs/template/public/main.js b/docs/template/public/main.js new file mode 100644 index 000000000..be4428bed --- /dev/null +++ b/docs/template/public/main.js @@ -0,0 +1,11 @@ +// From https://github.com/dotnet/docfx/discussions/9644 + +export default { + iconLinks: [ + { + icon: 'github', + href: 'https://github.com/json-api-dotnet/JsonApiDotNetCore', + title: 'GitHub' + } + ] +} diff --git a/docs/toc.yml b/docs/toc.yml index e9165998e..29f786ca4 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,17 +1,12 @@ - name: Getting Started - href: getting-started/ - + href: getting-started/index.md - name: Usage href: usage/ - - name: API href: api/ - homepage: api/index.md - + topicHref: api/index.md - name: Examples - href: request-examples/ - homepage: request-examples/index.md - + href: request-examples/index.md - name: Internals href: internals/ - homepage: internals/index.md + topicHref: internals/index.md diff --git a/docs/usage/advanced/alternate-routes.md b/docs/usage/advanced/alternate-routes.md new file mode 100644 index 000000000..a860a61fa --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/archiving.md b/docs/usage/advanced/archiving.md new file mode 100644 index 000000000..3892877a5 --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/auth-scopes.md b/docs/usage/advanced/auth-scopes.md new file mode 100644 index 000000000..e37cb1b6a --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/blobs.md b/docs/usage/advanced/blobs.md new file mode 100644 index 000000000..d3d4525c6 --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/composite-keys.md b/docs/usage/advanced/composite-keys.md new file mode 100644 index 000000000..768a22a19 --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/content-negotiation.md b/docs/usage/advanced/content-negotiation.md new file mode 100644 index 000000000..980b2e0b6 --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/eager-loading.md b/docs/usage/advanced/eager-loading.md new file mode 100644 index 000000000..72e401c4f --- /dev/null +++ b/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. diff --git a/docs/usage/advanced/error-handling.md b/docs/usage/advanced/error-handling.md new file mode 100644 index 000000000..c53b3f266 --- /dev/null +++ b/docs/usage/advanced/error-handling.md @@ -0,0 +1,13 @@ +# Error Handling + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/ExceptionHandling) shows how to customize error handling. + +A user-defined exception, `ConsumerArticleIsNoLongerAvailableException`, is thrown from a resource service to demonstrate handling it. +Note that this exception can be thrown from anywhere during request execution; a resource service is just used here for simplicity. + +To handle the user-defined exception, `AlternateExceptionHandler` inherits from `ExceptionHandler` to: +- Customize the JSON:API error response by adding a `meta` entry when `ConsumerArticleIsNoLongerAvailableException` is thrown. +- Indicate that `ConsumerArticleIsNoLongerAvailableException` must be logged at the Warning level. + +Additionally, the `ThrowingArticle.Status` property throws an `InvalidOperationException`. +This triggers the default error handling because `AlternateExceptionHandler` delegates to its base class. diff --git a/docs/usage/advanced/hosting-iis.md b/docs/usage/advanced/hosting-iis.md new file mode 100644 index 000000000..f452adaee --- /dev/null +++ b/docs/usage/advanced/hosting-iis.md @@ -0,0 +1,7 @@ +# Hosting in Internet Information Services (IIS) + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/HostingInIIS) calls [UsePathBase](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.usepathbaseextensions.usepathbase) to simulate hosting in IIS. +For details on how `UsePathBase` works, see [Understanding PathBase in ASP.NET Core](https://andrewlock.net/understanding-pathbase-in-aspnetcore/). + +- At startup, the line `app.UsePathBase("/iis-application-virtual-directory")` configures ASP.NET to use the base path. +- `PaintingsController` uses a custom route to demonstrate that both features can be used together. diff --git a/docs/usage/advanced/id-obfuscation.md b/docs/usage/advanced/id-obfuscation.md new file mode 100644 index 000000000..4012238c2 --- /dev/null +++ b/docs/usage/advanced/id-obfuscation.md @@ -0,0 +1,16 @@ +# ID Obfuscation + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/IdObfuscation) shows how to use obfuscated IDs. +They are typically used to prevent clients from guessing primary key values. + +All IDs sent by clients are transparently de-obfuscated into internal numeric values before accessing the database. +Numeric IDs returned from the database are obfuscated before they are sent to the client. + +> [!NOTE] +> An alternate solution is to use GUIDs instead of numeric primary keys in the database. + +ID obfuscation is achieved using the following extensibility points: + +- For simplicity, `HexadecimalCodec` is used to obfuscate numeric IDs to a hexadecimal format. A more realistic use case would be to use a symmetric crypto algorithm. +- `ObfuscatedIdentifiable` acts as the base class for resource types, handling the obfuscation and de-obfuscation of IDs. +- `ObfuscatedIdentifiableController` acts as the base class for controllers. It inherits from `BaseJsonApiController`, changing the `id` parameter in action methods to type `string`. diff --git a/docs/usage/advanced/index.md b/docs/usage/advanced/index.md new file mode 100644 index 000000000..6bf9841db --- /dev/null +++ b/docs/usage/advanced/index.md @@ -0,0 +1,19 @@ +# Advanced JSON:API features + +This topic goes beyond the basics of what's possible with JsonApiDotNetCore. + +Advanced use cases are provided in the form of integration tests [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests). +This ensures they don't break during development of the framework. + +Each directory typically contains: + +- A set of resource types. +- A `DbContext` class to register the resource types. +- Fakers to generate deterministic test data. +- Test classes that assert the feature works as expected. + - Entities are inserted into a randomly named PostgreSQL database. + - An HTTP request is sent. + - The returned response is asserted on. + - If applicable, the changes are fetched from the database and asserted on. + +To run/debug the integration tests, follow the steps in [README.md](https://github.com/json-api-dotnet/JsonApiDotNetCore#build-from-source). diff --git a/docs/usage/advanced/links.md b/docs/usage/advanced/links.md new file mode 100644 index 000000000..d26be8756 --- /dev/null +++ b/docs/usage/advanced/links.md @@ -0,0 +1,19 @@ +# Links + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/Links) shows various ways to configure which links are returned, and how they appear in responses. + +> [!TIP] +> By default, absolute links are returned. To return relative links, set [JsonApiOptions.UseRelativeLinks](~/usage/options.md#relative-links) at startup. + +> [!TIP] +> To add a global prefix to all routes, set `JsonApiOptions.Namespace` at startup. + +Which links to render can be configured globally in options, then overridden per resource type, and then overridden per relationship. + +- The `PhotoLocation` resource type turns off `TopLevelLinks` and `ResourceLinks`, and sets `RelationshipLinks` to `Related`. +- The `PhotoLocation.Album` relationship turns off all links for this relationship. + +The various tests set `JsonApiOptions.Namespace` and `JsonApiOptions.UseRelativeLinks` to verify that the proper links are rendered. +This can't be set in the tests directly for technical reasons, so they use different `Startup` classes to control this. + +Link rendering is fully controlled using attributes on your models. No further code is needed. diff --git a/docs/usage/advanced/microservices.md b/docs/usage/advanced/microservices.md new file mode 100644 index 000000000..88e9cb08b --- /dev/null +++ b/docs/usage/advanced/microservices.md @@ -0,0 +1,22 @@ +# Microservices + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/Microservices) shows patterns commonly used in microservices architecture: + +- [Fire-and-forget](https://microservices.io/patterns/communication-style/messaging.html): Outgoing messages are sent to an external queue, without waiting for their processing to start. While this is the simplest solution, it is not very reliable when errors occur. +- [Transactional Outbox Pattern](https://microservices.io/patterns/data/transactional-outbox.html): Outgoing messages are saved to a queue table within the same database transaction. A background job (omitted in this example) polls the queue table and sends the messages to an external queue. + +> [!TIP] +> Potential external queue systems you could use are [RabbitMQ](https://www.rabbitmq.com/), [MassTransit](https://masstransit.io/), +> [Azure Service Bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview) and [Apache Kafka](https://kafka.apache.org/). However, this is beyond the scope of this topic. + +The `Messages` directory lists the functional messages that are created from incoming JSON:API requests, which are typically processed by an external system that handles messages from the queue. +Each message has a unique ID and type, and is versioned to support gradual deployments. +Example payloads of messages are: user created, user login name changed, user moved to group, group created, group renamed, etc. + +The abstract types `MessagingGroupDefinition` and `MessagingUserDefinition` are resource definitions that contain code shared by both patterns. They inspect the incoming request and produce one or more functional messages from it. +The pattern-specific derived types inject their `DbContext`, which is used to query for additional information when determining what is being changed. + +> [!NOTE] +> Because networks are inherently unreliable, systems that consume messages from an external queue should be [idempotent](https://microservices.io/patterns/communication-style/idempotent-consumer.html). +> Several years ago, a [prototype](https://github.com/json-api-dotnet/JsonApiDotNetCore/pull/1132) was built to make JSON:API idempotent, but it was never finished due to a lack of community interest. +> Please [open an issue](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/new?labels=enhancement) if idempotency matters to you. diff --git a/docs/usage/advanced/model-state.md b/docs/usage/advanced/model-state.md new file mode 100644 index 000000000..0117cd72e --- /dev/null +++ b/docs/usage/advanced/model-state.md @@ -0,0 +1,14 @@ +# ASP.NET Model Validation + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/InputValidation/ModelState) shows how to use [ASP.NET Model Validation](https://learn.microsoft.com/aspnet/web-api/overview/formats-and-model-binding/model-validation-in-aspnet-web-api) attributes. + +> [!TIP] +> See [Atomic Operations](~/usage/advanced/operations.md) for how to implement a custom model validator. + +The resource types are decorated with Model Validation attributes, such as `[Required]`, `[RegularExpression]`, `[MinLength]`, and `[Range]`. + +Only the fields that appear in a request body (partial POST/PATCH) are validated. +When validation fails, the source pointer in the response indicates which attribute(s) are invalid. + +Model Validation is enabled by default, but can be [turned off in options](~/usage/options.md#modelstate-validation). +Aside from adding validation attributes to your resource properties, no further code is needed. diff --git a/docs/usage/advanced/multi-tenancy.md b/docs/usage/advanced/multi-tenancy.md new file mode 100644 index 000000000..d6e5b73f6 --- /dev/null +++ b/docs/usage/advanced/multi-tenancy.md @@ -0,0 +1,21 @@ +# Multi-tenancy + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/MultiTenancy) shows how to handle multiple tenants in a single database. + +> [!TIP] +> To use a different database per tenant, see [this](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples/DatabasePerTenantExample) example instead. +> Its `DbContext` dynamically sets the connection string per request. This requires the database structure to be identical for all tenants. + +The essence of implementing multi-tenancy within a single database is instructing Entity Framework Core to add implicit filters when entities are queried. +See the usage of `HasQueryFilter` in the `DbContext` class. It injects an `ITenantProvider` to determine the active tenant for the current HTTP request. + +> [!NOTE] +> For simplicity, this example uses a route parameter to indicate the active tenant. +> Provide your own `ITenantProvider` to determine the tenant from somewhere else, such as the incoming OAuth token. + +The generic `MultiTenantResourceService` transparently sets the tenant ID when creating a new resource. +Furthermore, it performs extra queries to ensure relationship changes apply to the current tenant, and to produce better error messages. + +While `MultiTenantResourceService` is used for both resource types, _only_ the `WebShop` resource type implements `IHasTenant`. +The related resource type `WebProduct` does not. Because the products table has a foreign key to the (tenant-specific) shop it belongs to, it doesn't need a `TenantId` column. +When a JSON:API request for web products executes, the `HasQueryFilter` in the `DbContext` ensures that only products belonging to the tenant-specific shop are returned. diff --git a/docs/usage/advanced/operations.md b/docs/usage/advanced/operations.md new file mode 100644 index 000000000..aec2b9fe4 --- /dev/null +++ b/docs/usage/advanced/operations.md @@ -0,0 +1,15 @@ +# Atomic Operations + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/AtomicOperations) covers usage of the [Atomic Operations](https://jsonapi.org/ext/atomic/) extension, which enables sending multiple changes in a single request. + +- Operations for creating, updating, and deleting resources and relationships are shown. +- If one of the operations fails, the transaction is rolled back. +- Local IDs are used to reference resources created in a preceding operation within the same request. +- A custom controller restricts which operations are allowed, per resource type. +- The maximum number of operations per request can be configured at startup. +- For efficiency, operations are validated upfront (before accessing the database). If validation fails, the list of all errors is returned. + - Takes [ASP.NET Model Validation](https://learn.microsoft.com/aspnet/web-api/overview/formats-and-model-binding/model-validation-in-aspnet-web-api) attributes into account. + - See `DateMustBeInThePastAttribute` for how to implement a custom model validator. +- Various interactions with resource definitions are shown. + +The Atomic Operations extension is enabled after an operations controller is added to the project. No further code is needed. diff --git a/docs/usage/advanced/query-string-functions.md b/docs/usage/advanced/query-string-functions.md new file mode 100644 index 000000000..214228d65 --- /dev/null +++ b/docs/usage/advanced/query-string-functions.md @@ -0,0 +1,23 @@ +# Query String Functions + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/QueryStrings/CustomFunctions) shows how to define custom functions that clients can use in JSON:API query string parameters. + +- IsUpperCase: Adds the `isUpperCase` function, which can be used in filters on `string` attributes. + - Returns whether the attribute value is uppercase. + - Example usage: `GET /blogs/1/posts?filter=and(isUpperCase(caption),not(isUpperCase(url)))` +- StringLength: Adds the `length` function, which can be used in filters and sorts on `string` attributes. + - Returns the number of characters in the attribute value. + - Example filter usage: `GET /blogs?filter=greaterThan(length(title),'2')` + - Example sort usage: `GET /blogs/1/posts?sort=length(caption),-length(url)` +- Sum: Adds the `sum` function, which can be used in filters. + - Returns the sum of the numeric attribute values in related resources. + - Example: `GET /blogPosts?filter=greaterThan(sum(comments,numStars),'4')` +- TimeOffset: Adds the `timeOffset` function, which can be used in filters on `DateTime` attributes. + - Calculates the difference between the attribute value and the current date. + - A generic resource definition intercepts all filters, rewriting the usage of `timeOffset` into the equivalent filters on the target attribute. + - Example: `GET /reminders?filter=greaterOrEqual(remindsAt,timeOffset('+0:10:00'))` + +The basic pattern to implement a custom function is to: +- Define a custom expression type, which inherits from one of the built-in expression types, such as `FilterExpression` or `FunctionExpression`. +- Inherit from one of the built-in parsers, such as `FilterParser` or `SortParser`, to convert tokens to your custom expression type. Override the `ParseFilter` or `ParseFunction` method. +- Inherit from one of the built-in query clause builders, such as `WhereClauseBuilder` or `OrderClauseBuilder`, to produce a LINQ expression for your custom expression type. Override the `DefaultVisit` method. diff --git a/docs/usage/advanced/resource-injection.md b/docs/usage/advanced/resource-injection.md new file mode 100644 index 000000000..c4e82a40f --- /dev/null +++ b/docs/usage/advanced/resource-injection.md @@ -0,0 +1,11 @@ +# Injecting services in resource types + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/ResourceConstructorInjection) shows how to inject services into resource types. + +Because Entity Framework Core doesn't support injecting arbitrary services into entity types (only a few special types), a workaround is used. +Instead of injecting the desired services directly, the `DbContext` is injected, which injects the desired services and exposes them via properties. + +- The `PostOffice` and `GiftCertificate` resource types both inject the `DbContext` in their constructors. +- The `DbContext` injects `TimeProvider` and exposes it through a property. +- `GiftCertificate` obtains the `TimeProvider` via the `DbContext` property to calculate the value for its exposed `HasExpired` property, which depends on the current time. +- `PostOffice` obtains the `TimeProvider` via the `DbContext` property to calculate the value for its exposed `IsOpen` property, which depends on the current time. diff --git a/docs/usage/advanced/soft-deletion.md b/docs/usage/advanced/soft-deletion.md new file mode 100644 index 000000000..cebc18e91 --- /dev/null +++ b/docs/usage/advanced/soft-deletion.md @@ -0,0 +1,15 @@ +# Soft Deletion + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/SoftDeletion) demonstrates how to implement soft deletion of resources. + +> [!TIP] +> This scenario is comparable with [Archiving](~/usage/advanced/archiving.md). +> The difference is that soft-deleted resources are never accessible by JSON:API clients (despite still being stored in the database), whereas archived resources _are_ accessible. + +The essence of implementing soft deletion is instructing Entity Framework Core to add implicit filters when entities are queried. +See the usage of `HasQueryFilter` in the `DbContext` class. + +The `ISoftDeletable` interface provides the `SoftDeletedAt` database column. The `Company` and `Department` resource types implement this interface to indicate they use soft deletion. + +The generic `SoftDeletionAwareResourceService` overrides the `DeleteAsync` method to soft-delete a resource instead of truly deleting it, if it implements `ISoftDeletable`. +Furthermore, it performs extra queries to ensure relationship changes do not reference soft-deleted resources, and to produce better error messages. diff --git a/docs/usage/advanced/state-machine.md b/docs/usage/advanced/state-machine.md new file mode 100644 index 000000000..371300995 --- /dev/null +++ b/docs/usage/advanced/state-machine.md @@ -0,0 +1,11 @@ +# State Transitions in Resource Updates + +The code [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests/InputValidation/RequestBody) shows how to validate state transitions when updating a resource. + +This feature is implemented using a custom resource definition: + +- The `Workflow` resource type contains a `Stage` property of type `WorkflowStage`. +- The `WorkflowStage` enumeration lists a workflow's possible states. +- `WorkflowDefinition` contains a hard-coded stage transition table defining the valid transitions. For example, a workflow in stage `InProgress` can be changed to `OnHold` or `Canceled`, but not `Created`. + - The `OnPrepareWriteAsync` method is overridden to capture the stage currently stored in the database in the `_previousStage` private field. + - The `OnWritingAsync` method is overridden to verify whether the stage change is permitted. It consults the stage transition table to determine whether there's a path from `_previousStage` to the to-be-stored stage, producing an error if there isn't. diff --git a/docs/usage/advanced/toc.yml b/docs/usage/advanced/toc.yml new file mode 100644 index 000000000..9d45cd04b --- /dev/null +++ b/docs/usage/advanced/toc.yml @@ -0,0 +1,38 @@ +- name: Authorization Scopes + href: auth-scopes.md +- name: BLOBs + href: blobs.md +- name: Microservices + href: microservices.md +- name: Multi-tenancy + href: multi-tenancy.md +- name: Atomic Operations + href: operations.md +- name: Query String Functions + href: query-string-functions.md +- name: Alternate Routes + href: alternate-routes.md +- name: Content Negotiation + href: content-negotiation.md +- name: Error Handling + href: error-handling.md +- name: Hosting in IIS + href: hosting-iis.md +- name: ID Obfuscation + href: id-obfuscation.md +- name: Soft Deletion + href: soft-deletion.md +- name: Archiving + href: archiving.md +- name: ASP.NET Model Validation + href: model-state.md +- name: State Transitions in Resource Updates + href: state-machine.md +- name: Links + href: links.md +- name: Composite Keys + href: composite-keys.md +- name: Eager Loading + href: eager-loading.md +- name: Injecting services in resource types + href: resource-injection.md diff --git a/docs/usage/caching.md b/docs/usage/caching.md index 28d6a6a36..4243fd8be 100644 --- a/docs/usage/caching.md +++ b/docs/usage/caching.md @@ -4,8 +4,8 @@ _since v4.2_ GET requests return an [ETag](https://developer.mozilla.org/docs/Web/HTTP/Headers/ETag) HTTP header, which can be used by the client in subsequent requests to save network bandwidth. -Be aware that the returned ETag represents the entire response body (a 'resource' in HTTP terminology) for a request URL that includes the query string. -This is unrelated to JSON:API resources. Therefore, we do not use ETags for optimistic concurrency. +Be aware that the returned ETag represents the entire response body (a "resource" in HTTP terminology) for the full request URL, including the query string. +A resource in HTTP is unrelated to a JSON:API resource. Therefore, we do not use ETags for optimistic concurrency. Getting a list of resources returns an ETag: @@ -26,7 +26,7 @@ ETag: "7FFF010786E2CE8FC901896E83870E00" } ``` -The request is later resent using the received ETag. The server data has not changed at this point. +The request is later resent using the same ETag received earlier. The server data has not changed at this point. ```http GET /articles?sort=-lastModifiedAt HTTP/1.1 diff --git a/docs/usage/extensibility/toc.yml b/docs/usage/extensibility/toc.yml new file mode 100644 index 000000000..4a32581a6 --- /dev/null +++ b/docs/usage/extensibility/toc.yml @@ -0,0 +1,14 @@ +- name: Layer Overview + href: layer-overview.md +- name: Resource Definitions + href: resource-definitions.md +- name: Controllers + href: controllers.md +- name: Resource Services + href: services.md +- name: Resource Repositories + href: repositories.md +- name: Middleware + href: middleware.md +- name: Query Strings + href: query-strings.md diff --git a/docs/usage/faq.md b/docs/usage/faq.md new file mode 100644 index 000000000..dacd35889 --- /dev/null +++ b/docs/usage/faq.md @@ -0,0 +1,176 @@ +# Frequently Asked Questions + +#### Where can I find documentation and examples? +While the [documentation](~/usage/resources/index.md) covers basic features and a few runnable example projects are available [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples), +many more advanced use cases are available as integration tests [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests), so be sure to check them out! + +#### Why don't you use the built-in OpenAPI support in ASP.NET Core? +The structure of JSON:API request and response bodies differs significantly from the signature of JsonApiDotNetCore controllers. +JsonApiDotNetCore provides OpenAPI support using [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore), a mature and feature-rich library that is highly extensible. +The [OpenAPI support in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview) is still very young +and doesn't provide the level of extensibility needed for JsonApiDotNetCore. + +#### What's available to implement a JSON:API client? +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 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. + +#### 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**. + +After turning on [Source Link](https://devblogs.microsoft.com/dotnet/improving-debug-time-productivity-with-source-link/#enabling-source-link) (which enables to download the JsonApiDotNetCore source code from GitHub), you can step into our source code and add breakpoints there too. + +Here are some key places in the execution pipeline to set a breakpoint: +- `JsonApiRoutingConvention.Apply`: Controllers are registered here (executes once at startup) +- `JsonApiMiddleware.InvokeAsync`: Content negotiation and `IJsonApiRequest` setup +- `QueryStringReader.ReadAll`: Parses the query string parameters +- `JsonApiReader.ReadAsync`: Parses the request body +- `OperationsProcessor.ProcessAsync`: Entry point for handling atomic operations +- `JsonApiResourceService`: Called by controllers, delegating to the repository layer +- `EntityFrameworkCoreRepository.ApplyQueryLayer`: Builds the `IQueryable<>` that is offered to Entity Framework Core (which turns it into SQL) +- `JsonApiWriter.WriteAsync`: Renders the response body +- `ExceptionHandler.HandleException`: Interception point for thrown exceptions + +Aside from debugging, you can get more info by: +- Including exception stack traces and incoming request bodies in error responses, as well as writing human-readable JSON: + + ```c# + // Program.cs + builder.Services.AddJsonApi(options => + { + options.IncludeExceptionStackTraceInErrors = true; + options.IncludeRequestBodyInErrors = true; + options.SerializerOptions.WriteIndented = true; + }); + ``` +- Turning on verbose logging and logging of executed SQL statements, by adding the following to your `appsettings.Development.json`: + + ```json + { + "Logging": { + "LogLevel": { + "Default": "Warning", + "Microsoft.EntityFrameworkCore.Database.Command": "Information", + "JsonApiDotNetCore": "Verbose" + } + } + } + ``` + +#### What if my JSON:API resources do not exactly match the shape of my database tables? +We often find users trying to write custom code to solve that. They usually get it wrong or incomplete, and it may not perform well. +Or it simply fails because it cannot be translated to SQL. +The good news is that there's an easier solution most of the time: configure Entity Framework Core mappings to do the work. + +For example, if your primary key column is named "CustomerId" instead of "Id": +```c# +builder.Entity().Property(x => x.Id).HasColumnName("CustomerId"); +``` + +It certainly pays off to read up on these capabilities at [Creating and Configuring a Model](https://learn.microsoft.com/ef/core/modeling/). +Another great resource is [Learn Entity Framework Core](https://www.learnentityframeworkcore.com/configuration). + +#### Can I share my resource models with .NET Framework projects? +Yes, you can. Put your model classes in a separate project that only references [JsonApiDotNetCore.Annotations](https://www.nuget.org/packages/JsonApiDotNetCore.Annotations/). +This package contains just the JSON:API attributes and targets NetStandard 1.0, which makes it flexible to consume. +At startup, use [Auto-discovery](~/usage/resource-graph.md#auto-discovery) and point it to your shared project. + +#### What's the best place to put my custom business/validation logic? +For basic input validation, use the attributes from [ASP.NET ModelState Validation](https://learn.microsoft.com/aspnet/core/mvc/models/validation?source=recommendations&view=aspnetcore-7.0#built-in-attributes) to get the best experience. +JsonApiDotNetCore is aware of them and adjusts behavior accordingly. And it produces the best possible error responses. + +For non-trivial business rules that require custom code, the place to be is [Resource Definitions](~/usage/extensibility/resource-definitions.md). +They provide a callback-based model where you can respond to everything going on. +The great thing is that your callbacks are invoked for various endpoints. +For example, the filter callback on Author executes at `GET /authors?filter=`, `GET /books/1/authors?filter=` and `GET /books?include=authors?filter[authors]=`. +Likewise, the callbacks for changing relationships execute for POST/PATCH resource endpoints, as well as POST/PATCH/DELETE relationship endpoints. + +#### Can API users send multiple changes in a single request? +Yes, just activate [atomic operations](~/usage/writing/bulk-batch-operations.md). +It enables sending multiple changes in a batch request, which are executed in a database transaction. +If something fails, all changes are rolled back. The error response indicates which operation failed. + +#### Is there any way to add `[Authorize(Roles = "...")]` to the generated controllers? +Sure, this is possible. Simply add the attribute at the class level. +See the docs on [Augmenting controllers](~/usage/extensibility/controllers.md#augmenting-controllers). + +#### How do I expose non-JSON:API endpoints? +You can add your own controllers that do not derive from `(Base)JsonApiController` or `(Base)JsonApiOperationsController`. +Whatever you do in those is completely ignored by JsonApiDotNetCore. +This is useful if you want to add a few RPC-style endpoints or provide binary file uploads/downloads. + +A middle-ground approach is to add custom action methods to existing JSON:API controllers. +While you can route them as you like, they must return JSON:API resources. +And on error, a JSON:API error response is produced. +This is useful if you want to stay in the JSON:API-compliant world, but need to expose something non-standard, for example: `GET /users/me`. + +#### How do I optimize for high scalability and prevent denial of service? +Fortunately, JsonApiDotNetCore [scales pretty well](https://github.com/json-api-dotnet/PerformanceReports) under high load and/or large database tables. +It never executes filtering, sorting, or pagination in-memory and tries pretty hard to produce the most efficient query possible. +There are a few things to keep in mind, though: +- Prevent users from executing slow queries by locking down [attribute capabilities](~/usage/resources/attributes.md#capabilities) and [relationship capabilities](~/usage/resources/relationships.md#capabilities). + Ensure the right database indexes are in place for what you enable. +- Prevent users from fetching lots of data by tweaking [maximum page size/number](~/usage/options.md#pagination) and [maximum include depth](~/usage/options.md#maximum-include-depth). +- Avoid long-running transactions by tweaking `MaximumOperationsPerRequest` in options. +- Tell your users to utilize [E-Tags](~/usage/caching.md) to reduce network traffic. +- Not included in JsonApiDotNetCore: Apply general practices such as rate limiting, load balancing, authentication/authorization, blocking very large URLs/request bodies, etc. + +#### Can I offload requests to a background process? +Yes, that's possible. Override controller methods to return `HTTP 202 Accepted`, with a `Location` HTTP header where users can retrieve the result. +Your controller method needs to store the request state (URL, query string, and request body) in a queue, which your background process can read from. +From within your background process job handler, reconstruct the request state, execute the appropriate `JsonApiResourceService` method and store the result. +There's a basic example available at https://github.com/json-api-dotnet/JsonApiDotNetCore/pull/1144, which processes a captured query string. + +#### What if I want to use something other than Entity Framework Core? +This basically means you'll need to implement data access yourself. There are two approaches for interception: at the resource service level and at the repository level. +Either way, you can use the built-in query string and request body parsing, as well as routing, error handling, and rendering of responses. + +Here are some injectable request-scoped types to be aware of: +- `IJsonApiRequest`: This contains routing information, such as whether a primary, secondary, or relationship endpoint is being accessed. +- `ITargetedFields`: Lists the attributes and relationships from an incoming POST/PATCH resource request. Any fields missing there should not be stored (partial updates). +- `IEnumerable`: Provides access to the parsed query string parameters. +- `IEvaluatedIncludeCache`: This tells the response serializer which related resources to render. +- `ISparseFieldSetCache`: This tells the response serializer which fields to render in the `attributes` and `relationships` objects. + +You may also want to inject the singletons `IJsonApiOptions` (which contains settings such as default page size) and `IResourceGraph` (the JSON:API model of resources, attributes and relationships). + +So, back to the topic of where to intercept. It helps to familiarize yourself with the [execution pipeline](~/internals/queries.md). +Replacing at the service level is the simplest. But it means you'll need to read the parsed query string parameters and invoke +all resource definition callbacks yourself. And you won't get change detection (HTTP 203 Not Modified). +Take a look at [JsonApiResourceService](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Services/JsonApiResourceService.cs) to see what you're missing out on. + +You'll get a lot more out of the box if replacing at the repository level instead. You don't need to apply options or analyze query strings. +And most resource definition callbacks are handled. +That's because the built-in resource service translates all JSON:API query aspects of the request into a database-agnostic data structure called `QueryLayer`. +Now the hard part for you becomes reading that data structure and producing data access calls from that. +If your data store provides a LINQ provider, you can probably reuse [QueryableBuilder](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Queries/QueryableBuilding/QueryableBuilder.cs), +which drives the translation into [System.Linq.Expressions](https://learn.microsoft.com/dotnet/csharp/programming-guide/concepts/expression-trees/). +Note however, that it also produces calls to `.Include("")`, which is an Entity Framework Core-specific extension method, so you'll need to +[prevent that from happening](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/JsonApiDotNetCore/Queries/QueryableBuilding/QueryLayerIncludeConverter.cs). + +The example [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/Examples/NoEntityFrameworkExample/Repositories/InMemoryResourceRepository.cs) compiles and executes +the LINQ query against an in-memory list of resources. +For [MongoDB](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb/blob/master/src/JsonApiDotNetCore.MongoDb/Repositories/MongoRepository.cs), we use the MongoDB LINQ provider. +If there's no LINQ provider available, the example [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/src/Examples/DapperExample/Repositories/DapperRepository.cs) may be of help, +which produces SQL and uses [Dapper](https://github.com/DapperLib/Dapper) for data access. + +> [!TIP] +> [ExpressionTreeVisualizer](https://github.com/zspitz/ExpressionTreeVisualizer) is very helpful in trying to debug LINQ expression trees! + +#### I love JsonApiDotNetCore! How can I support the team? +The best way to express your gratitude is by starring our repository. +This increases our leverage when asking for bug fixes in dependent projects, such as the .NET runtime and Entity Framework Core. +You can also [sponsor](https://github.com/sponsors/json-api-dotnet) our project. +Of course, a simple thank-you message in our [Gitter channel](https://gitter.im/json-api-dotnet-core/Lobby) is appreciated too! + +If you'd like to do more: try things out, ask questions, create GitHub bug reports or feature requests, or upvote existing issues that are important to you. +We welcome PRs, but keep in mind: The worst thing in the world is opening a PR that gets rejected after you've put a lot of effort into it. +So for any non-trivial changes, please open an issue first to discuss your approach and ensure it fits the product vision. + +#### Is there anything else I should be aware of? +See [Common Pitfalls](~/usage/common-pitfalls.md). diff --git a/docs/usage/reading/toc.yml b/docs/usage/reading/toc.yml new file mode 100644 index 000000000..aa1ecb6bc --- /dev/null +++ b/docs/usage/reading/toc.yml @@ -0,0 +1,10 @@ +- name: Filtering + href: filtering.md +- name: Sorting + href: sorting.md +- name: Pagination + href: pagination.md +- name: Sparse Fieldset Selection + href: sparse-fieldset-selection.md +- name: Including Related Resources + href: including-relationships.md diff --git a/docs/usage/resources/index.md b/docs/usage/resources/index.md index f8e7d2915..09e0224c5 100644 --- a/docs/usage/resources/index.md +++ b/docs/usage/resources/index.md @@ -22,10 +22,9 @@ public class Person : Identifiable } ``` -If your resource must inherit from another class, -you can always implement the interface yourself. -In this example, `ApplicationUser` inherits from `IdentityUser` -which already contains an Id property of type string. +If your resource must inherit from another class, you can always implement the interface yourself. +In this example, `ApplicationUser` inherits from [`IdentityUser`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.identity.entityframeworkcore.identityuser), +which already contains an `Id` property of type `string`. ```c# public class ApplicationUser : IdentityUser, IIdentifiable diff --git a/docs/usage/resources/inheritance.md b/docs/usage/resources/inheritance.md index 47cf85ca6..56c046ef8 100644 --- a/docs/usage/resources/inheritance.md +++ b/docs/usage/resources/inheritance.md @@ -143,7 +143,7 @@ GET /humans HTTP/1.1 } ``` -### Spare fieldsets +### Sparse fieldsets If you only want to retrieve the fields from the base type, you can use [sparse fieldsets](~/usage/reading/sparse-fieldset-selection.md). diff --git a/docs/usage/resources/toc.yml b/docs/usage/resources/toc.yml new file mode 100644 index 000000000..d4daf205d --- /dev/null +++ b/docs/usage/resources/toc.yml @@ -0,0 +1,8 @@ +- name: Attributes + href: attributes.md +- name: Relationships + href: relationships.md +- name: Inheritance + href: inheritance.md +- name: Nullability + href: nullability.md diff --git a/docs/usage/toc.md b/docs/usage/toc.md deleted file mode 100644 index bdeb0e495..000000000 --- a/docs/usage/toc.md +++ /dev/null @@ -1,39 +0,0 @@ -# [Resources](resources/index.md) -## [Attributes](resources/attributes.md) -## [Relationships](resources/relationships.md) -## [Inheritance](resources/inheritance.md) -## [Nullability](resources/nullability.md) - -# Reading data -## [Filtering](reading/filtering.md) -## [Sorting](reading/sorting.md) -## [Pagination](reading/pagination.md) -## [Sparse Fieldset Selection](reading/sparse-fieldset-selection.md) -## [Including Relationships](reading/including-relationships.md) - -# Writing data -## [Creating](writing/creating.md) -## [Updating](writing/updating.md) -## [Deleting](writing/deleting.md) -## [Bulk/batch](writing/bulk-batch-operations.md) - -# [Resource Graph](resource-graph.md) -# [Options](options.md) -# [Routing](routing.md) -# [Errors](errors.md) -# [Metadata](meta.md) -# [Caching](caching.md) -# [Common Pitfalls](common-pitfalls.md) - -# [OpenAPI](openapi.md) -## [Documentation](openapi-documentation.md) -## [Clients](openapi-client.md) - -# Extensibility -## [Layer Overview](extensibility/layer-overview.md) -## [Resource Definitions](extensibility/resource-definitions.md) -## [Controllers](extensibility/controllers.md) -## [Resource Services](extensibility/services.md) -## [Resource Repositories](extensibility/repositories.md) -## [Middleware](extensibility/middleware.md) -## [Query Strings](extensibility/query-strings.md) diff --git a/docs/usage/toc.yml b/docs/usage/toc.yml new file mode 100644 index 000000000..f5d60e9a1 --- /dev/null +++ b/docs/usage/toc.yml @@ -0,0 +1,35 @@ +- name: FAQ + href: faq.md +- name: Common Pitfalls + href: common-pitfalls.md +- name: Resources + href: resources/toc.yml + topicHref: resources/index.md +- name: Reading data + href: reading/toc.yml +- name: Writing data + href: writing/toc.yml +- name: Resource Graph + href: resource-graph.md +- name: Options + href: options.md +- name: Routing + href: routing.md +- name: Errors + href: errors.md +- name: Metadata + href: meta.md +- name: Caching + href: caching.md +- name: OpenAPI + href: openapi.md + items: + - name: Documentation + href: openapi-documentation.md + - name: Clients + href: openapi-client.md +- name: Extensibility + href: extensibility/toc.yml +- name: Advanced + href: advanced/toc.yml + topicHref: advanced/index.md diff --git a/docs/usage/writing/toc.yml b/docs/usage/writing/toc.yml new file mode 100644 index 000000000..db836e548 --- /dev/null +++ b/docs/usage/writing/toc.yml @@ -0,0 +1,8 @@ +- name: Creating + href: creating.md +- name: Updating + href: updating.md +- name: Deleting + href: deleting.md +- name: Bulk/Batch + href: bulk-batch-operations.md diff --git a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiException.cs b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiException.cs index 8b66839e9..a86118c87 100644 --- a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiException.cs +++ b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiException.cs @@ -5,6 +5,13 @@ namespace JsonApiDotNetCore.OpenApi.Client.NSwag; +///

+/// Replacement for the auto-generated +/// +/// ApiException +/// +/// class from NSwag. +///

[UsedImplicitly(ImplicitUseTargetFlags.Members)] public class ApiException(string message, int statusCode, string? response, IReadOnlyDictionary> headers, Exception? innerException) : Exception($"HTTP {statusCode}: {message}", innerException) @@ -14,6 +21,13 @@ public class ApiException(string message, int statusCode, string? response, IRea public IReadOnlyDictionary> Headers { get; } = headers; } +///

+/// Replacement for the auto-generated +/// +/// ApiException<TResult> +/// +/// class from NSwag. +///

[UsedImplicitly(ImplicitUseTargetFlags.Members)] public sealed class ApiException( string message, int statusCode, string? response, IReadOnlyDictionary> headers, TResult result, Exception? innerException) diff --git a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiResponse.cs b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiResponse.cs index 74ee77127..7d3d7c2a5 100644 --- a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiResponse.cs +++ b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/ApiResponse.cs @@ -3,6 +3,13 @@ namespace JsonApiDotNetCore.OpenApi.Client.NSwag; +///

+/// Replacement for the auto-generated +/// +/// SwaggerResponse +/// +/// class from NSwag. +///

[PublicAPI] public class ApiResponse(int statusCode, IReadOnlyDictionary> headers) { @@ -71,6 +78,13 @@ public static async Task TranslateAsync(Func> ope } } +///

+/// Replacement for the auto-generated +/// +/// SwaggerResponse<TResult> +/// +/// class from NSwag. +///

[PublicAPI] public class ApiResponse(int statusCode, IReadOnlyDictionary> headers, TResult result) : ApiResponse(statusCode, headers) diff --git a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/BlockedJsonInheritanceConverter.cs b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/BlockedJsonInheritanceConverter.cs index a3a7e627d..602bacce6 100644 --- a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/BlockedJsonInheritanceConverter.cs +++ b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/BlockedJsonInheritanceConverter.cs @@ -4,6 +4,13 @@ namespace JsonApiDotNetCore.OpenApi.Client.NSwag; // Referenced from liquid template, to ensure the built-in JsonInheritanceConverter from NSwag is never used. +///

+/// Exists to block usage of the default +/// +/// JsonInheritanceConverter +/// +/// from NSwag, which is incompatible with JSON:API. +///

[PublicAPI] public abstract class BlockedJsonInheritanceConverter : JsonConverter { @@ -31,11 +38,17 @@ public override bool CanConvert(Type objectType) return true; } + ///

+ /// Always throws an . + ///

public override void WriteJson(JsonWriter writer, object? value, JsonSerializer serializer) { throw new InvalidOperationException("JsonInheritanceConverter is incompatible with JSON:API and must not be used."); } + ///

+ /// Always throws an . + ///

public override object ReadJson(JsonReader reader, Type objectType, object? existingValue, JsonSerializer serializer) { throw new InvalidOperationException("JsonInheritanceConverter is incompatible with JSON:API and must not be used."); diff --git a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/IJsonApiClient.cs b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/IJsonApiClient.cs deleted file mode 100644 index df6a35d78..000000000 --- a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/IJsonApiClient.cs +++ /dev/null @@ -1,41 +0,0 @@ -using System.Linq.Expressions; -using JetBrains.Annotations; - -namespace JsonApiDotNetCore.OpenApi.Client.NSwag; - -[PublicAPI] -public interface IJsonApiClient -{ - ///

- /// Ensures correct serialization of JSON:API attributes in the request body of a POST/PATCH request at a resource endpoint. Properties with default - /// values are omitted, unless explicitly included using - /// - /// In JSON:API, an omitted attribute indicates to ignore it, while an attribute that is set to null means to clear it. This poses a problem, - /// because the serializer cannot distinguish between "you have explicitly set this .NET property to its default value" vs "you didn't touch it, so it - /// contains its default value" when converting to JSON. - /// - ///

- /// - /// The request document instance for which default values should be omitted. - /// - /// - /// Optional. A list of lambda expressions that indicate which properties to always include in the JSON request body. For example: - ///

 video.Title, video => video.Summary
-    /// ]]>

- /// - /// - /// The type of the request document. - /// - /// - /// The type of the attributes object inside . - /// - /// - /// An to clear the current registration. For efficient memory usage, it is recommended to wrap calls to this method in a - /// using statement, so the registrations are cleaned up after executing the request. After disposal, the client can be reused without the - /// registrations added earlier. - /// - IDisposable WithPartialAttributeSerialization(TRequestDocument requestDocument, - params Expression>[] alwaysIncludedAttributeSelectors) - where TRequestDocument : class; -} diff --git a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/NotifyPropertySet.cs b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/NotifyPropertySet.cs index 80adb5647..111b89487 100644 --- a/src/JsonApiDotNetCore.OpenApi.Client.NSwag/NotifyPropertySet.cs +++ b/src/JsonApiDotNetCore.OpenApi.Client.NSwag/NotifyPropertySet.cs @@ -11,7 +11,8 @@ namespace JsonApiDotNetCore.OpenApi.Client.NSwag; ///

-/// Implementation of that doesn't detect changes. +/// Implementation of that unconditionally raises the event when a property is +/// assigned. Exists to support JSON:API partial POST/PATCH. ///

[PublicAPI] public abstract class NotifyPropertySet : INotifyPropertyChanged From c41dae3f8b7ed9eae11421f8dabf811e96a5c011 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Tue, 6 May 2025 04:52:22 +0200 Subject: [PATCH 03/17] Update links in README.md to new documentation --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8dd6a6ecf..5ab49fae3 100644 --- a/README.md +++ b/README.md @@ -203,8 +203,8 @@ The following links explain what this project provides, why it exists, and how y ### Samples -- The [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory provides ready-to-run sample API projects -- Many advanced use cases are covered by integration tests, which can be found [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests). +- The [examples](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples) directory provides ready-to-run sample API projects, which are documented [here](https://www.jsonapi.net/request-examples/index.html). +- The [integration tests](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests) directory covers many advanced use cases, which are documented [here](https://www.jsonapi.net/usage/advanced/index.html). This includes topics such as batching, multi-tenancy, authorization, soft-deletion, obfuscated IDs, resource inheritance, alternate routing, custom metadata, error handling and logging. - The [Ember.js Todo List App](https://github.com/json-api-dotnet/TodoListExample) showcases a JsonApiDotNetCore API and an Ember.js client with token authentication. From d94b2e5d6767b2b96adb5fcf1d81db38f6564c13 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Tue, 6 May 2025 05:12:08 +0200 Subject: [PATCH 04/17] Add sitemap to documentation website --- docs/docfx.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docfx.json b/docs/docfx.json index 25a4aa943..b073247dd 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -45,6 +45,11 @@ "globalMetadata": { "_appLogoPath": "styles/img/favicon.png", "_googleAnalyticsTagId": "G-78GTGF1FM2" + }, + "sitemap": { + "baseUrl": "https://www.jsonapi.net", + "priority": 0.5, + "changefreq": "weekly" } } } From 80a6875dc11741d061214b89f58be31fa3b0a093 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Tue, 6 May 2025 05:55:35 +0200 Subject: [PATCH 05/17] Throw better exception in corner cases --- .../Configuration/ResourceType.cs | 1 - .../Configuration/ApplicationBuilderExtensions.cs | 3 ++- src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs b/src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs index 3cda945d7..4c0cd133f 100644 --- a/src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs +++ b/src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs @@ -173,7 +173,6 @@ public AttrAttribute GetAttributeByPublicName(string publicName) public AttrAttribute GetAttributeByPropertyName(string propertyName) { AttrAttribute? attribute = FindAttributeByPropertyName(propertyName); - return attribute ?? throw new InvalidOperationException($"Attribute for property '{propertyName}' does not exist on resource type '{ClrType.Name}'."); } diff --git a/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs b/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs index 3957a2883..19e0ffc87 100644 --- a/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs +++ b/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs @@ -1,3 +1,4 @@ +using JsonApiDotNetCore.Errors; using JsonApiDotNetCore.Middleware; using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.DependencyInjection; @@ -60,7 +61,7 @@ private static void AssertAspNetCoreOpenApiIsNotRegistered(IServiceProvider serv if (configureInstance != null) { - throw new InvalidOperationException("JsonApiDotNetCore is incompatible with ASP.NET OpenAPI. " + + throw new InvalidConfigurationException("JsonApiDotNetCore is incompatible with ASP.NET OpenAPI. " + "Replace 'services.AddOpenApi()' with 'services.AddOpenApiForJsonApi()' from the JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package."); } } diff --git a/src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs b/src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs index fcf18f97a..8ab2120d9 100644 --- a/src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs +++ b/src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs @@ -455,7 +455,7 @@ private static void AssertNoInfiniteRecursion(int recursionDepth) { if (recursionDepth >= 500) { - throw new InvalidOperationException("Infinite recursion detected in eager-load chain."); + throw new InvalidConfigurationException("Infinite recursion detected in eager-load chain."); } } From 762bb4f8fe4f4065b8477bc15c56996d91415c20 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Tue, 6 May 2025 06:49:33 +0200 Subject: [PATCH 06/17] Fix broken test, adjust message --- .../Configuration/ApplicationBuilderExtensions.cs | 3 ++- test/DiscoveryTests/AspNetOpenApiTests.cs | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs b/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs index 19e0ffc87..fb69fa5ae 100644 --- a/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs +++ b/src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs @@ -62,7 +62,8 @@ private static void AssertAspNetCoreOpenApiIsNotRegistered(IServiceProvider serv if (configureInstance != null) { throw new InvalidConfigurationException("JsonApiDotNetCore is incompatible with ASP.NET OpenAPI. " + - "Replace 'services.AddOpenApi()' with 'services.AddOpenApiForJsonApi()' from the JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package."); + "Remove 'services.AddOpenApi()', or replace it by calling 'services.AddOpenApiForJsonApi()' after 'services.AddJsonApi()' " + + "from the JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package."); } } } diff --git a/test/DiscoveryTests/AspNetOpenApiTests.cs b/test/DiscoveryTests/AspNetOpenApiTests.cs index 20619f4cc..06dfcee91 100644 --- a/test/DiscoveryTests/AspNetOpenApiTests.cs +++ b/test/DiscoveryTests/AspNetOpenApiTests.cs @@ -1,6 +1,7 @@ #if !NET8_0 using FluentAssertions; using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Errors; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.TestHost; using Microsoft.Extensions.DependencyInjection; @@ -24,8 +25,9 @@ public async Task Throws_when_AspNet_OpenApi_is_registered() Action action = app.UseJsonApi; // Assert - action.Should().ThrowExactly().WithMessage("JsonApiDotNetCore is incompatible with ASP.NET OpenAPI. " + - "Replace 'services.AddOpenApi()' with 'services.AddOpenApiForJsonApi()' from the JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package."); + action.Should().ThrowExactly().WithMessage("JsonApiDotNetCore is incompatible with ASP.NET OpenAPI. " + + "Remove 'services.AddOpenApi()', or replace it by calling 'services.AddOpenApiForJsonApi()' after 'services.AddJsonApi()' " + + "from the JsonApiDotNetCore.OpenApi.Swashbuckle NuGet package."); } } #endif From b6b56b05f472bbc4f8efef2dceaf52d3d16532d0 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Wed, 21 May 2025 04:53:36 +0200 Subject: [PATCH 07/17] Package updates, fix max connections exceeded from Build.ps1 (#1730) --- .config/dotnet-tools.json | 2 +- Build.ps1 | 3 +-- package-versions.props | 8 ++++---- run-docker-postgres.ps1 | 2 +- 4 files changed, 7 insertions(+), 8 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 4b173d25f..f14a93f95 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -17,7 +17,7 @@ "rollForward": false }, "dotnet-reportgenerator-globaltool": { - "version": "5.4.5", + "version": "5.4.7", "commands": [ "reportgenerator" ], diff --git a/Build.ps1 b/Build.ps1 index 6c6ff9c13..1c369bd1a 100644 --- a/Build.ps1 +++ b/Build.ps1 @@ -5,8 +5,7 @@ function VerifySuccessExitCode { } Write-Host "$(pwsh --version)" -Write-Host "Active .NET SDK: $(dotnet --version)" -Write-Host "Using version suffix: $versionSuffix" +Write-Host ".NET SDK $(dotnet --version)" Remove-Item -Recurse -Force artifacts -ErrorAction SilentlyContinue Remove-Item -Recurse -Force * -Include coverage.cobertura.xml diff --git a/package-versions.props b/package-versions.props index 8b528ff32..d14ed838b 100644 --- a/package-versions.props +++ b/package-versions.props @@ -11,7 +11,7 @@ 0.14.* 1.0.* 35.6.* - 4.13.* + 4.14.* 6.0.* 2.1.* 7.2.* @@ -20,12 +20,12 @@ 1.* 9.0.* 9.0.* - 14.3.* + 14.4.* 13.0.* - 2.1.* + 2.3.* 8.*-* 9.0.* - 17.13.* + 17.14.* 2.9.* 2.8.* diff --git a/run-docker-postgres.ps1 b/run-docker-postgres.ps1 index 0cd42b389..25b631a7a 100644 --- a/run-docker-postgres.ps1 +++ b/run-docker-postgres.ps1 @@ -11,7 +11,7 @@ param( docker container stop jsonapi-postgresql-db docker container stop jsonapi-postgresql-management -docker run --pull always --rm --detach --name jsonapi-postgresql-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:latest +docker run --pull always --rm --detach --name jsonapi-postgresql-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:latest -N 500 if ($UI) { docker run --pull always --rm --detach --name jsonapi-postgresql-management --link jsonapi-postgresql-db:db -e PGADMIN_DEFAULT_EMAIL=admin@admin.com -e PGADMIN_DEFAULT_PASSWORD=postgres -p 5050:80 dpage/pgadmin4:latest From 99c9a95c77e882906666aed52918f2da4f63b633 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sun, 25 May 2025 13:10:56 +0200 Subject: [PATCH 08/17] Log QueryLayer and LINQ expression at Debug level (#1732) * Log QueryLayer and Expression at Debug level * Replace debugger visualizer link in docs --- docs/usage/faq.md | 2 +- package-versions.props | 1 + .../Middleware/TraceLogWriter.cs | 39 +++++++ .../ExpressionTreeFormatter.cs | 53 +++++++++ .../EntityFrameworkCoreRepository.cs | 4 + test/DiscoveryTests/DiscoveryTests.csproj | 3 +- test/DiscoveryTests/LoggingTests.cs | 52 +++++++++ .../Mixed/AtomicTraceLoggingTests.cs | 2 +- .../IntegrationTests/Logging/Fruit.cs | 3 + .../IntegrationTests/Logging/LoggingFakers.cs | 2 + .../IntegrationTests/Logging/LoggingTests.cs | 102 +++++++++++++++++- .../JsonApiDotNetCoreTests.csproj | 1 + 12 files changed, 257 insertions(+), 7 deletions(-) create mode 100644 src/JsonApiDotNetCore/Queries/QueryableBuilding/ExpressionTreeFormatter.cs create mode 100644 test/DiscoveryTests/LoggingTests.cs diff --git a/docs/usage/faq.md b/docs/usage/faq.md index dacd35889..567f17525 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -160,7 +160,7 @@ If there's no LINQ provider available, the example [here](https://github.com/jso which produces SQL and uses [Dapper](https://github.com/DapperLib/Dapper) for data access. > [!TIP] -> [ExpressionTreeVisualizer](https://github.com/zspitz/ExpressionTreeVisualizer) is very helpful in trying to debug LINQ expression trees! +> [ReadableExpressions](https://github.com/agileobjects/ReadableExpressions) is very helpful in trying to debug LINQ expression trees! #### I love JsonApiDotNetCore! How can I support the team? The best way to express your gratitude is by starring our repository. diff --git a/package-versions.props b/package-versions.props index d14ed838b..0403a83c0 100644 --- a/package-versions.props +++ b/package-versions.props @@ -22,6 +22,7 @@ 9.0.* 14.4.* 13.0.* + 4.1.* 2.3.* 8.*-* 9.0.* diff --git a/src/JsonApiDotNetCore/Middleware/TraceLogWriter.cs b/src/JsonApiDotNetCore/Middleware/TraceLogWriter.cs index 70ed7fdd0..23e6733a4 100644 --- a/src/JsonApiDotNetCore/Middleware/TraceLogWriter.cs +++ b/src/JsonApiDotNetCore/Middleware/TraceLogWriter.cs @@ -1,3 +1,4 @@ +using System.Linq.Expressions; using System.Reflection; using System.Runtime.CompilerServices; using System.Text; @@ -5,6 +6,8 @@ using System.Text.Json; using System.Text.Json.Serialization; using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Queries; +using JsonApiDotNetCore.Queries.QueryableBuilding; using JsonApiDotNetCore.Resources; using JsonApiDotNetCore.Resources.Annotations; using Microsoft.Extensions.Logging; @@ -204,9 +207,45 @@ private static string SerializeObject(object? value) } } + public void LogDebug(QueryLayer queryLayer) + { + ArgumentNullException.ThrowIfNull(queryLayer); + + LogQueryLayer(queryLayer); + } + + public void LogDebug(Expression expression) + { + ArgumentNullException.ThrowIfNull(expression); + + if (_logger.IsEnabled(LogLevel.Debug)) + { + string? text = ExpressionTreeFormatter.Instance.GetText(expression); + + if (text != null) + { + LogExpression(text); + } + else + { + LogReadableExpressionsAssemblyUnavailable(); + } + } + } + [LoggerMessage(Level = LogLevel.Trace, SkipEnabledCheck = true, Message = "Entering {MemberName}({ParameterValues})")] private partial void LogEnteringMemberWithParameters(string memberName, string parameterValues); [LoggerMessage(Level = LogLevel.Trace, SkipEnabledCheck = true, Message = "Entering {MemberName}()")] private partial void LogEnteringMember(string memberName); + + [LoggerMessage(Level = LogLevel.Debug, Message = "QueryLayer: {queryLayer}")] + private partial void LogQueryLayer(QueryLayer queryLayer); + + [LoggerMessage(Level = LogLevel.Debug, SkipEnabledCheck = true, Message = "Expression tree: {expression}")] + private partial void LogExpression(string expression); + + [LoggerMessage(Level = LogLevel.Debug, SkipEnabledCheck = true, + Message = "Failed to load assembly. To log expression trees, add a NuGet reference to 'AgileObjects.ReadableExpressions' in your project.")] + private partial void LogReadableExpressionsAssemblyUnavailable(); } diff --git a/src/JsonApiDotNetCore/Queries/QueryableBuilding/ExpressionTreeFormatter.cs b/src/JsonApiDotNetCore/Queries/QueryableBuilding/ExpressionTreeFormatter.cs new file mode 100644 index 000000000..c6b1bc4bb --- /dev/null +++ b/src/JsonApiDotNetCore/Queries/QueryableBuilding/ExpressionTreeFormatter.cs @@ -0,0 +1,53 @@ +using System.Linq.Expressions; +using System.Reflection; + +namespace JsonApiDotNetCore.Queries.QueryableBuilding; + +///

+/// Converts a to readable text, if the AgileObjects.ReadableExpressions NuGet package is referenced. +///

+internal sealed class ExpressionTreeFormatter +{ + private static readonly Lazy LazyToReadableStringMethod = new(GetToReadableStringMethod, LazyThreadSafetyMode.ExecutionAndPublication); + + public static ExpressionTreeFormatter Instance { get; } = new(); + + private ExpressionTreeFormatter() + { + } + + private static MethodInvoker? GetToReadableStringMethod() + { + Assembly? assembly = TryLoadAssembly(); + Type? type = assembly?.GetType("AgileObjects.ReadableExpressions.ExpressionExtensions", false); + MethodInfo? method = type?.GetMethods(BindingFlags.Public | BindingFlags.Static).FirstOrDefault(method => method.Name == "ToReadableString"); + return method != null ? MethodInvoker.Create(method) : null; + } + + private static Assembly? TryLoadAssembly() + { + try + { + return Assembly.Load("AgileObjects.ReadableExpressions"); + } + catch (Exception exception) when (exception is ArgumentException or IOException or BadImageFormatException) + { + } + + return null; + } + + public string? GetText(Expression expression) + { + ArgumentNullException.ThrowIfNull(expression); + + try + { + return LazyToReadableStringMethod.Value?.Invoke(null, expression, null) as string; + } + catch (Exception exception) when (exception is TargetException or InvalidOperationException or TargetParameterCountException or NotSupportedException) + { + return null; + } + } +} diff --git a/src/JsonApiDotNetCore/Repositories/EntityFrameworkCoreRepository.cs b/src/JsonApiDotNetCore/Repositories/EntityFrameworkCoreRepository.cs index 214987828..f4c9af37c 100644 --- a/src/JsonApiDotNetCore/Repositories/EntityFrameworkCoreRepository.cs +++ b/src/JsonApiDotNetCore/Repositories/EntityFrameworkCoreRepository.cs @@ -122,6 +122,8 @@ protected virtual IQueryable ApplyQueryLayer(QueryLayer queryLayer) ArgumentNullException.ThrowIfNull(queryLayer); + _traceWriter.LogDebug(queryLayer); + using (CodeTimingSessionManager.Current.Measure("Convert QueryLayer to System.Expression")) { IQueryable source = GetAll(); @@ -151,6 +153,8 @@ protected virtual IQueryable ApplyQueryLayer(QueryLayer queryLayer) var context = QueryableBuilderContext.CreateRoot(source, typeof(Queryable), _dbContext.Model, null); Expression expression = builder.ApplyQuery(queryLayer, context); + _traceWriter.LogDebug(expression); + using (CodeTimingSessionManager.Current.Measure("Convert System.Expression to IQueryable")) { return source.Provider.CreateQuery(expression); diff --git a/test/DiscoveryTests/DiscoveryTests.csproj b/test/DiscoveryTests/DiscoveryTests.csproj index 825056684..11567b911 100644 --- a/test/DiscoveryTests/DiscoveryTests.csproj +++ b/test/DiscoveryTests/DiscoveryTests.csproj @@ -1,4 +1,4 @@ - + net9.0;net8.0 @@ -15,5 +15,6 @@ + diff --git a/test/DiscoveryTests/LoggingTests.cs b/test/DiscoveryTests/LoggingTests.cs new file mode 100644 index 000000000..9afb7c788 --- /dev/null +++ b/test/DiscoveryTests/LoggingTests.cs @@ -0,0 +1,52 @@ +using FluentAssertions; +using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Queries; +using JsonApiDotNetCore.Repositories; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.TestHost; +using Microsoft.EntityFrameworkCore; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; +using TestBuildingBlocks; +using Xunit; + +namespace DiscoveryTests; + +public sealed class LoggingTests +{ + [Fact] + public async Task Logs_message_to_add_NuGet_reference() + { + // Arrange + using var loggerProvider = + new CapturingLoggerProvider((category, _) => category.StartsWith("JsonApiDotNetCore.Repositories", StringComparison.Ordinal)); + + WebApplicationBuilder builder = WebApplication.CreateEmptyBuilder(new WebApplicationOptions()); + builder.Logging.AddProvider(loggerProvider); + builder.Logging.SetMinimumLevel(LogLevel.Debug); + builder.Services.AddDbContext(options => options.UseInMemoryDatabase(Guid.NewGuid().ToString())); + builder.Services.AddJsonApi(); + builder.WebHost.UseTestServer(); + await using WebApplication app = builder.Build(); + + var resourceGraph = app.Services.GetRequiredService(); + ResourceType resourceType = resourceGraph.GetResourceType(); + + var repository = app.Services.GetRequiredService>(); + + // Act + _ = await repository.GetAsync(new QueryLayer(resourceType), CancellationToken.None); + + // Assert + IReadOnlyList logLines = loggerProvider.GetLines(); + + logLines.Should().Contain( + "[DEBUG] Failed to load assembly. To log expression trees, add a NuGet reference to 'AgileObjects.ReadableExpressions' in your project."); + } + + private sealed class TestDbContext(DbContextOptions options) + : DbContext(options) + { + public DbSet PrivateResources => Set(); + } +} diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/AtomicOperations/Mixed/AtomicTraceLoggingTests.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/AtomicOperations/Mixed/AtomicTraceLoggingTests.cs index 6eb2ce3a3..0ea01e7d3 100644 --- a/test/JsonApiDotNetCoreTests/IntegrationTests/AtomicOperations/Mixed/AtomicTraceLoggingTests.cs +++ b/test/JsonApiDotNetCoreTests/IntegrationTests/AtomicOperations/Mixed/AtomicTraceLoggingTests.cs @@ -22,7 +22,7 @@ public AtomicTraceLoggingTests(IntegrationTestContext { var loggerProvider = new CapturingLoggerProvider((category, level) => - level >= LogLevel.Trace && category.StartsWith("JsonApiDotNetCore.", StringComparison.Ordinal)); + level == LogLevel.Trace && category.StartsWith("JsonApiDotNetCore.", StringComparison.Ordinal)); options.AddProvider(loggerProvider); options.SetMinimumLevel(LogLevel.Trace); diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/Fruit.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/Fruit.cs index fd0fbf0df..4e26c558f 100644 --- a/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/Fruit.cs +++ b/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/Fruit.cs @@ -10,4 +10,7 @@ public abstract class Fruit : Identifiable { [Attr] public abstract string Color { get; } + + [Attr] + public double WeightInKilograms { get; set; } } diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingFakers.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingFakers.cs index a66cdcdf5..aa34ff32f 100644 --- a/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingFakers.cs +++ b/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingFakers.cs @@ -15,10 +15,12 @@ internal sealed class LoggingFakers private readonly Lazy> _lazyBananaFaker = new(() => new Faker() .MakeDeterministic() + .RuleFor(banana => banana.WeightInKilograms, faker => faker.Random.Double(.2, .3)) .RuleFor(banana => banana.LengthInCentimeters, faker => faker.Random.Double(10, 25))); private readonly Lazy> _lazyPeachFaker = new(() => new Faker() .MakeDeterministic() + .RuleFor(peach => peach.WeightInKilograms, faker => faker.Random.Double(.2, .3)) .RuleFor(peach => peach.DiameterInCentimeters, faker => faker.Random.Double(6, 7.5))); public Faker AuditEntry => _lazyAuditEntryFaker.Value; diff --git a/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingTests.cs b/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingTests.cs index 9fbd9e805..4d35403f9 100644 --- a/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingTests.cs +++ b/test/JsonApiDotNetCoreTests/IntegrationTests/Logging/LoggingTests.cs @@ -152,9 +152,9 @@ await _testContext.RunOnDatabaseAsync(async dbContext => responseDocument.Should().BeEmpty(); - IReadOnlyList logLines = loggerProvider.GetLines(); + string[] traceLines = loggerProvider.GetMessages().Where(message => message.LogLevel == LogLevel.Trace).Select(message => message.ToString()).ToArray(); - logLines.Should().BeEquivalentTo(new[] + traceLines.Should().BeEquivalentTo(new[] { $$""" [TRACE] Received POST request at 'http://localhost/fruitBowls/{{existingBowl.StringId}}/relationships/fruits' with body: <<{ @@ -215,6 +215,7 @@ [TRACE] Entering AddToToManyRelationshipAsync(leftResource: null, leftId: {{exis { "Color": "Yellow", "LengthInCentimeters": {{existingBanana.LengthInCentimeters.ToString(CultureInfo.InvariantCulture)}}, + "WeightInKilograms": {{existingBanana.WeightInKilograms.ToString(CultureInfo.InvariantCulture)}}, "Id": {{existingBanana.Id}}, "StringId": "{{existingBanana.StringId}}" } @@ -262,9 +263,9 @@ await _testContext.RunOnDatabaseAsync(async dbContext => responseDocument.Should().BeEmpty(); - IReadOnlyList logLines = loggerProvider.GetLines(); + string[] traceLines = loggerProvider.GetMessages().Where(message => message.LogLevel == LogLevel.Trace).Select(message => message.ToString()).ToArray(); - logLines.Should().BeEquivalentTo(new[] + traceLines.Should().BeEquivalentTo(new[] { $$""" [TRACE] Received POST request at 'http://localhost/fruitBowls/{{existingBowl.StringId}}/relationships/fruits' with body: <<{ @@ -281,6 +282,7 @@ [TRACE] Entering PostRelationshipAsync(id: {{existingBowl.StringId}}, relationsh { "Color": "Red/Yellow", "DiameterInCentimeters": 0, + "WeightInKilograms": 0, "Id": {{existingPeach.Id}}, "StringId": "{{existingPeach.StringId}}" } @@ -291,6 +293,7 @@ [TRACE] Entering AddToToManyRelationshipAsync(leftId: {{existingBowl.StringId}}, { "Color": "Red/Yellow", "DiameterInCentimeters": 0, + "WeightInKilograms": 0, "Id": {{existingPeach.Id}}, "StringId": "{{existingPeach.StringId}}" } @@ -329,6 +332,7 @@ [TRACE] Entering AddToToManyRelationshipAsync(leftResource: null, leftId: {{exis { "Color": "Red/Yellow", "DiameterInCentimeters": 0, + "WeightInKilograms": 0, "Id": {{existingPeach.Id}}, "StringId": "{{existingPeach.StringId}}" } @@ -336,4 +340,94 @@ [TRACE] Entering AddToToManyRelationshipAsync(leftResource: null, leftId: {{exis """ }, options => options.Using(IgnoreLineEndingsComparer.Instance).WithStrictOrdering()); } + + [Fact] + public async Task Logs_query_layer_and_expression_at_Debug_level() + { + // Arrange + var loggerProvider = _testContext.Factory.Services.GetRequiredService(); + loggerProvider.Clear(); + + var bowl = new FruitBowl(); + bowl.Fruits.Add(_fakers.Peach.GenerateOne()); + + await _testContext.RunOnDatabaseAsync(async dbContext => + { + dbContext.FruitBowls.Add(bowl); + await dbContext.SaveChangesAsync(); + }); + + string route = $"/fruitBowls/{bowl.StringId}/fruits?filter=greaterThan(weightInKilograms,'0.1')&fields[peaches]=color&sort=-id"; + + // Act + (HttpResponseMessage httpResponse, string responseDocument) = await _testContext.ExecuteGetAsync(route); + + // Assert + httpResponse.ShouldHaveStatusCode(HttpStatusCode.OK); + + responseDocument.Should().NotBeEmpty(); + + LogMessage queryLayerMessage = loggerProvider.GetMessages().Should() + .ContainSingle(message => message.LogLevel == LogLevel.Debug && message.Text.StartsWith("QueryLayer:", StringComparison.Ordinal)).Subject; + + queryLayerMessage.Text.Should().Be($$""" + QueryLayer: QueryLayer + { + Include: fruits + Filter: equals(id,'{{bowl.StringId}}') + Selection + { + FieldSelectors + { + id + fruits: QueryLayer + { + Filter: greaterThan(weightInKilograms,'0.1') + Sort: -id + Pagination: Page number: 1, size: 10 + Selection + { + FieldSelectors + { + color + id + } + } + } + } + } + } + + """); + + LogMessage expressionMessage = loggerProvider.GetMessages().Should().ContainSingle(message => + message.LogLevel == LogLevel.Debug && message.Text.StartsWith("Expression tree:", StringComparison.Ordinal)).Subject; + + expressionMessage.Text.Should().Be(""" + Expression tree: [Microsoft.EntityFrameworkCore.Query.EntityQueryRootExpression] + .AsNoTrackingWithIdentityResolution() + .Include("Fruits") + .Where(fruitBowl => fruitBowl.Id == value) + .Select( + fruitBowl => new FruitBowl + { + Id = fruitBowl.Id, + Fruits = fruitBowl.Fruits + .Where(fruit => fruit.WeightInKilograms > value) + .OrderByDescending(fruit => fruit.Id) + .Take(value) + .Select( + fruit => (fruit.GetType() == value) + ? (Fruit)new Peach + { + Id = fruit.Id, + WeightInKilograms = fruit.WeightInKilograms, + DiameterInCentimeters = ((Peach)fruit).DiameterInCentimeters, + Id = fruit.Id + } + : fruit) + .ToHashSet() + }) + """); + } } diff --git a/test/JsonApiDotNetCoreTests/JsonApiDotNetCoreTests.csproj b/test/JsonApiDotNetCoreTests/JsonApiDotNetCoreTests.csproj index 6bc5a666a..bdfea682d 100644 --- a/test/JsonApiDotNetCoreTests/JsonApiDotNetCoreTests.csproj +++ b/test/JsonApiDotNetCoreTests/JsonApiDotNetCoreTests.csproj @@ -12,6 +12,7 @@ + From 6b6ba1f663ae91f4a669a88d66d0ea56af764bc2 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sun, 25 May 2025 13:44:14 +0200 Subject: [PATCH 09/17] Update list of kiota bugs --- docs/usage/openapi-client.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/openapi-client.md b/docs/usage/openapi-client.md index 58b9ca87e..277d28021 100644 --- a/docs/usage/openapi-client.md +++ b/docs/usage/openapi-client.md @@ -340,8 +340,8 @@ demonstrates how to use them. It uses local IDs to: | --- | --- | --- | | Properties are always nullable | - | https://github.com/microsoft/kiota/issues/3911 | | JSON:API query strings are inaccessible | Use `SetQueryStringHttpMessageHandler.CreateScope` from `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/3800 | -| Properties set to `null` are sent twice | - | https://github.com/microsoft/kiota-dotnet/issues/535 | | HTTP 304 (Not Modified) is not properly recognized | Catch `ApiException` and inspect the response status code | https://github.com/microsoft/kiota/issues/4190, https://github.com/microsoft/kiota-dotnet/issues/531 | +| No `Accept` header sent when only error responses define `Content-Type` | `JsonApiDotNetCore.OpenApi.Swashbuckle` package contains workaround | https://github.com/microsoft/kiota/issues/6572 | | Generator warns about unsupported formats | Use `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/4227 | | `Stream` response for HEAD request | - | https://github.com/microsoft/kiota/issues/4245 | | Unhelpful exception messages | - | https://github.com/microsoft/kiota/issues/4349 | From c00f55272eb46bd69c2b5bbcf64b5e82e0f6982d Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sun, 25 May 2025 13:56:00 +0200 Subject: [PATCH 10/17] Update documentation: advanced use cases and logging --- docs/usage/faq.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/usage/faq.md b/docs/usage/faq.md index 567f17525..cbb32c4c0 100644 --- a/docs/usage/faq.md +++ b/docs/usage/faq.md @@ -1,8 +1,7 @@ # Frequently Asked Questions #### Where can I find documentation and examples? -While the [documentation](~/usage/resources/index.md) covers basic features and a few runnable example projects are available [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples), -many more advanced use cases are available as integration tests [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/test/JsonApiDotNetCoreTests/IntegrationTests), so be sure to check them out! +The [documentation](~/usage/resources/index.md) covers basic features, as well as [advanced use cases](~/usage/advanced/index.md). Several runnable example projects are available [here](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/master/src/Examples). #### Why don't you use the built-in OpenAPI support in ASP.NET Core? The structure of JSON:API request and response bodies differs significantly from the signature of JsonApiDotNetCore controllers. @@ -48,7 +47,7 @@ Aside from debugging, you can get more info by: options.SerializerOptions.WriteIndented = true; }); ``` -- Turning on verbose logging and logging of executed SQL statements, by adding the following to your `appsettings.Development.json`: +- Turning on trace logging, or/and logging of executed SQL statements, by adding the following to your `appsettings.Development.json`: ```json { @@ -56,11 +55,12 @@ Aside from debugging, you can get more info by: "LogLevel": { "Default": "Warning", "Microsoft.EntityFrameworkCore.Database.Command": "Information", - "JsonApiDotNetCore": "Verbose" + "JsonApiDotNetCore": "Trace" } } } ``` +- Activate debug logging of LINQ expressions by adding a NuGet reference to [AgileObjects.ReadableExpressions](https://www.nuget.org/packages/AgileObjects.ReadableExpressions) in your project. #### What if my JSON:API resources do not exactly match the shape of my database tables? We often find users trying to write custom code to solve that. They usually get it wrong or incomplete, and it may not perform well. From 86cee8b10b624d7559bc07d3e4edb2b79e1541ee Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Mon, 2 Jun 2025 02:11:48 +0200 Subject: [PATCH 11/17] Remove redundant selectors in QueryLayer, only sort by ID when pagination enabled (#1735) --- src/JsonApiDotNetCore/Queries/QueryLayer.cs | 2 + .../Queries/QueryLayerComposer.cs | 59 ++++++++++++++----- .../QueryStrings/FilterTests.cs | 5 -- .../QueryStrings/IncludeTests.cs | 4 +- .../QueryStrings/SortTests.cs | 4 +- .../QueryStrings/SparseFieldSets.cs | 2 - .../Relationships/FetchRelationshipTests.cs | 1 - .../ReadWrite/Resources/FetchResourceTests.cs | 1 - .../Sql/SubQueryInJoinTests.cs | 23 ++++---- 9 files changed, 62 insertions(+), 39 deletions(-) diff --git a/src/JsonApiDotNetCore/Queries/QueryLayer.cs b/src/JsonApiDotNetCore/Queries/QueryLayer.cs index 1ff8e34dc..49a9ee92a 100644 --- a/src/JsonApiDotNetCore/Queries/QueryLayer.cs +++ b/src/JsonApiDotNetCore/Queries/QueryLayer.cs @@ -11,6 +11,8 @@ namespace JsonApiDotNetCore.Queries; [PublicAPI] public sealed class QueryLayer { + internal bool IsEmpty => Filter == null && Sort == null && Pagination?.PageSize == null && (Selection == null || Selection.IsEmpty); + public ResourceType ResourceType { get; } public IncludeExpression? Include { get; set; } diff --git a/src/JsonApiDotNetCore/Queries/QueryLayerComposer.cs b/src/JsonApiDotNetCore/Queries/QueryLayerComposer.cs index f7843b12c..7954aa0e7 100644 --- a/src/JsonApiDotNetCore/Queries/QueryLayerComposer.cs +++ b/src/JsonApiDotNetCore/Queries/QueryLayerComposer.cs @@ -173,13 +173,20 @@ private QueryLayer ComposeTopLayer(ImmutableArray constraints _paginationContext.PageSize = topPagination.PageSize; _paginationContext.PageNumber = topPagination.PageNumber; - return new QueryLayer(resourceType) + var topLayer = new QueryLayer(resourceType) { Filter = GetFilter(expressionsInTopScope, resourceType), Sort = GetSort(expressionsInTopScope, resourceType), Pagination = topPagination, Selection = GetSelectionForSparseAttributeSet(resourceType) }; + + if (topLayer is { Pagination.PageSize: not null, Sort: null }) + { + topLayer.Sort = CreateSortById(resourceType); + } + + return topLayer; } private IncludeExpression ComposeChildren(QueryLayer topLayer, ImmutableArray constraints) @@ -237,7 +244,7 @@ private IImmutableSet ProcessIncludeSet(IImmutableSet< ResourceType resourceType = includeElement.Relationship.RightType; bool isToManyRelationship = includeElement.Relationship is HasManyAttribute; - var child = new QueryLayer(resourceType) + var subLayer = new QueryLayer(resourceType) { Filter = isToManyRelationship ? GetFilter(expressionsInCurrentScope, resourceType) : null, Sort = isToManyRelationship ? GetSort(expressionsInCurrentScope, resourceType) : null, @@ -245,9 +252,14 @@ private IImmutableSet ProcessIncludeSet(IImmutableSet< Selection = GetSelectionForSparseAttributeSet(resourceType) }; - selectors.IncludeRelationship(includeElement.Relationship, child); + if (subLayer is { Pagination.PageSize: not null, Sort: null }) + { + subLayer.Sort = CreateSortById(resourceType); + } - IImmutableSet updatedChildren = ProcessIncludeSet(includeElement.Children, child, relationshipChain, constraints); + selectors.IncludeRelationship(includeElement.Relationship, subLayer); + + IImmutableSet updatedChildren = ProcessIncludeSet(includeElement.Children, subLayer, relationshipChain, constraints); if (!ReferenceEquals(includeElement.Children, updatedChildren)) { @@ -256,9 +268,30 @@ private IImmutableSet ProcessIncludeSet(IImmutableSet< } } + EliminateRedundantSelectors(parentLayer); + return updatesInChildren.Count == 0 ? includeElementsEvaluated : ApplyIncludeElementUpdates(includeElementsEvaluated, updatesInChildren); } + private static void EliminateRedundantSelectors(QueryLayer parentLayer) + { + if (parentLayer.Selection != null) + { + foreach ((ResourceType resourceType, FieldSelectors selectors) in parentLayer.Selection.ToArray()) + { + if (selectors.ContainsOnlyRelationships && selectors.Values.OfType().All(subLayer => subLayer.IsEmpty)) + { + parentLayer.Selection.Remove(resourceType); + } + } + + if (parentLayer.Selection.IsEmpty) + { + parentLayer.Selection = null; + } + } + } + private static ImmutableHashSet ApplyIncludeElementUpdates(IImmutableSet includeElements, Dictionary> updatesInChildren) { @@ -507,23 +540,21 @@ protected virtual IImmutableSet GetIncludeElements(IIm return _resourceDefinitionAccessor.OnApplyFilter(resourceType, filter); } - protected virtual SortExpression GetSort(IReadOnlyCollection expressionsInScope, ResourceType resourceType) + protected virtual SortExpression? GetSort(IReadOnlyCollection expressionsInScope, ResourceType resourceType) { ArgumentNullException.ThrowIfNull(expressionsInScope); ArgumentNullException.ThrowIfNull(resourceType); SortExpression? sort = expressionsInScope.OfType().FirstOrDefault(); - sort = _resourceDefinitionAccessor.OnApplySort(resourceType, sort); - - if (sort == null) - { - AttrAttribute idAttribute = GetIdAttribute(resourceType); - var idAscendingSort = new SortElementExpression(new ResourceFieldChainExpression(idAttribute), true); - sort = new SortExpression(ImmutableArray.Create(idAscendingSort)); - } + return _resourceDefinitionAccessor.OnApplySort(resourceType, sort); + } - return sort; + private SortExpression CreateSortById(ResourceType resourceType) + { + AttrAttribute idAttribute = GetIdAttribute(resourceType); + var idAscendingSort = new SortElementExpression(new ResourceFieldChainExpression(idAttribute), true); + return new SortExpression(ImmutableArray.Create(idAscendingSort)); } protected virtual PaginationExpression GetPagination(IReadOnlyCollection expressionsInScope, ResourceType resourceType) diff --git a/test/DapperTests/IntegrationTests/QueryStrings/FilterTests.cs b/test/DapperTests/IntegrationTests/QueryStrings/FilterTests.cs index f7da3533f..c303d7034 100644 --- a/test/DapperTests/IntegrationTests/QueryStrings/FilterTests.cs +++ b/test/DapperTests/IntegrationTests/QueryStrings/FilterTests.cs @@ -78,7 +78,6 @@ SELECT COUNT(*) FROM "Tags" AS t1 LEFT JOIN "RgbColors" AS t2 ON t1."Id" = t2."TagId" WHERE t2."Id" = @p1 - ORDER BY t1."Id" """)); command.Parameters.Should().HaveCount(1); @@ -144,7 +143,6 @@ SELECT COUNT(*) FROM "Tags" AS t1 LEFT JOIN "RgbColors" AS t2 ON t1."Id" = t2."TagId" WHERE t2."Id" IN (@p1, @p2) - ORDER BY t1."Id" """)); command.Parameters.Should().HaveCount(2); @@ -662,7 +660,6 @@ SELECT COUNT(*) SELECT t1."Id", t1."FirstName", t1."LastName" FROM "People" AS t1 WHERE (NOT (t1."FirstName" = @p1)) OR (t1."FirstName" IS NULL) - ORDER BY t1."Id" """)); command.Parameters.Should().HaveCount(1); @@ -867,7 +864,6 @@ SELECT COUNT(*) SELECT t1."Id", t1."Name" FROM "Tags" AS t1 WHERE (t1."Name" LIKE '%A\%%' ESCAPE '\') OR (t1."Name" LIKE '%A\_%' ESCAPE '\') OR (t1."Name" LIKE '%A\\%' ESCAPE '\') OR (t1."Name" LIKE '%A''%') OR (t1."Name" LIKE '%\%\_\\''%' ESCAPE '\') - ORDER BY t1."Id" """)); command.Parameters.Should().BeEmpty(); @@ -1177,7 +1173,6 @@ SELECT 1 LEFT JOIN "People" AS t3 ON t2."AssigneeId" = t3."Id" WHERE (t1."Id" = t2."OwnerId") AND (NOT (t3."Id" IS NULL)) AND (t3."FirstName" IS NULL) ) - ORDER BY t1."Id" """)); command.Parameters.Should().BeEmpty(); diff --git a/test/DapperTests/IntegrationTests/QueryStrings/IncludeTests.cs b/test/DapperTests/IntegrationTests/QueryStrings/IncludeTests.cs index 77805ee1b..84625b463 100644 --- a/test/DapperTests/IntegrationTests/QueryStrings/IncludeTests.cs +++ b/test/DapperTests/IntegrationTests/QueryStrings/IncludeTests.cs @@ -165,7 +165,7 @@ SELECT COUNT(*) INNER JOIN "People" AS t3 ON t1."OwnerId" = t3."Id" LEFT JOIN "TodoItems" AS t4 ON t3."Id" = t4."AssigneeId" LEFT JOIN "Tags" AS t5 ON t1."Id" = t5."TodoItemId" - ORDER BY t1."Priority", t1."LastModifiedAt" DESC, t4."Priority", t4."LastModifiedAt" DESC, t5."Id" + ORDER BY t1."Priority", t1."LastModifiedAt" DESC, t4."Priority", t4."LastModifiedAt" DESC """)); command.Parameters.Should().BeEmpty(); @@ -231,7 +231,7 @@ SELECT COUNT(*) FROM "TodoItems" AS t1 LEFT JOIN "Tags" AS t2 ON t1."Id" = t2."TodoItemId" LEFT JOIN "RgbColors" AS t3 ON t2."Id" = t3."TagId" - ORDER BY t1."Priority", t1."LastModifiedAt" DESC, t2."Id" + ORDER BY t1."Priority", t1."LastModifiedAt" DESC """)); command.Parameters.Should().BeEmpty(); diff --git a/test/DapperTests/IntegrationTests/QueryStrings/SortTests.cs b/test/DapperTests/IntegrationTests/QueryStrings/SortTests.cs index 488dda2cc..6a155d152 100644 --- a/test/DapperTests/IntegrationTests/QueryStrings/SortTests.cs +++ b/test/DapperTests/IntegrationTests/QueryStrings/SortTests.cs @@ -349,7 +349,7 @@ ORDER BY ( SELECT COUNT(*) FROM "Tags" AS t3 WHERE t2."Id" = t3."TodoItemId" - ) DESC, t2."Id", t4."Id" + ) DESC, t2."Id" """)); command.Parameters.Should().HaveCount(1); @@ -415,7 +415,7 @@ SELECT COUNT(*) SELECT t1."Id", t1."FirstName", t1."LastName", t2."Id", t2."CreatedAt", t2."Description", t2."DurationInHours", t2."LastModifiedAt", t2."Priority" FROM "People" AS t1 LEFT JOIN "TodoItems" AS t2 ON t1."Id" = t2."OwnerId" - ORDER BY t1."Id", ( + ORDER BY ( SELECT COUNT(*) FROM "Tags" AS t3 WHERE t2."Id" = t3."TodoItemId" diff --git a/test/DapperTests/IntegrationTests/QueryStrings/SparseFieldSets.cs b/test/DapperTests/IntegrationTests/QueryStrings/SparseFieldSets.cs index b2e0c68f8..a1d4524c9 100644 --- a/test/DapperTests/IntegrationTests/QueryStrings/SparseFieldSets.cs +++ b/test/DapperTests/IntegrationTests/QueryStrings/SparseFieldSets.cs @@ -215,7 +215,6 @@ SELECT COUNT(*) FROM "TodoItems" AS t1 LEFT JOIN "Tags" AS t2 ON t1."Id" = t2."TodoItemId" WHERE t1."Id" = @p1 - ORDER BY t2."Id" """)); command.Parameters.Should().HaveCount(1); @@ -400,7 +399,6 @@ await _testContext.RunOnDatabaseAsync(async dbContext => FROM "TodoItems" AS t1 LEFT JOIN "Tags" AS t2 ON t1."Id" = t2."TodoItemId" WHERE t1."Id" = @p1 - ORDER BY t2."Id" """)); command.Parameters.Should().HaveCount(1); diff --git a/test/DapperTests/IntegrationTests/ReadWrite/Relationships/FetchRelationshipTests.cs b/test/DapperTests/IntegrationTests/ReadWrite/Relationships/FetchRelationshipTests.cs index d4703dc99..9783672e6 100644 --- a/test/DapperTests/IntegrationTests/ReadWrite/Relationships/FetchRelationshipTests.cs +++ b/test/DapperTests/IntegrationTests/ReadWrite/Relationships/FetchRelationshipTests.cs @@ -168,7 +168,6 @@ SELECT COUNT(*) FROM "TodoItems" AS t1 LEFT JOIN "Tags" AS t2 ON t1."Id" = t2."TodoItemId" WHERE t1."Id" = @p1 - ORDER BY t2."Id" """)); command.Parameters.Should().HaveCount(1); diff --git a/test/DapperTests/IntegrationTests/ReadWrite/Resources/FetchResourceTests.cs b/test/DapperTests/IntegrationTests/ReadWrite/Resources/FetchResourceTests.cs index bd7139e5c..52bb378b2 100644 --- a/test/DapperTests/IntegrationTests/ReadWrite/Resources/FetchResourceTests.cs +++ b/test/DapperTests/IntegrationTests/ReadWrite/Resources/FetchResourceTests.cs @@ -246,7 +246,6 @@ SELECT COUNT(*) FROM "TodoItems" AS t1 LEFT JOIN "Tags" AS t2 ON t1."Id" = t2."TodoItemId" WHERE t1."Id" = @p1 - ORDER BY t2."Id" """)); command.Parameters.Should().HaveCount(1); diff --git a/test/DapperTests/IntegrationTests/Sql/SubQueryInJoinTests.cs b/test/DapperTests/IntegrationTests/Sql/SubQueryInJoinTests.cs index 8b7d18d2d..9b6e62f39 100644 --- a/test/DapperTests/IntegrationTests/Sql/SubQueryInJoinTests.cs +++ b/test/DapperTests/IntegrationTests/Sql/SubQueryInJoinTests.cs @@ -62,7 +62,6 @@ SELECT COUNT(*) SELECT t1."Id", t1."FirstName", t1."LastName", t2."Id", t2."LastUsedAt", t2."UserName" FROM "People" AS t1 LEFT JOIN "LoginAccounts" AS t2 ON t1."AccountId" = t2."Id" - ORDER BY t1."Id" """)); command.Parameters.Should().BeEmpty(); @@ -111,7 +110,7 @@ SELECT COUNT(*) SELECT t1."Id", t1."FirstName", t1."LastName", t2."Id", t2."CreatedAt", t2."Description", t2."DurationInHours", t2."LastModifiedAt", t2."Priority" FROM "People" AS t1 LEFT JOIN "TodoItems" AS t2 ON t1."Id" = t2."OwnerId" - ORDER BY t1."Id", t2."Priority", t2."LastModifiedAt" DESC + ORDER BY t2."Priority", t2."LastModifiedAt" DESC """)); command.Parameters.Should().BeEmpty(); @@ -160,7 +159,7 @@ SELECT COUNT(*) SELECT t1."Id", t1."FirstName", t1."LastName", t2."Id", t2."CreatedAt", t2."Description", t2."DurationInHours", t2."LastModifiedAt", t2."Priority" FROM "People" AS t1 LEFT JOIN "TodoItems" AS t2 ON t1."Id" = t2."OwnerId" - ORDER BY t1."Id", t2."Description" + ORDER BY t2."Description" """)); command.Parameters.Should().BeEmpty(); @@ -209,7 +208,7 @@ SELECT COUNT(*) SELECT t1."Id", t1."FirstName", t1."LastName", t2."Id", t2."CreatedAt", t2."Description", t2."DurationInHours", t2."LastModifiedAt", t2."Priority" FROM "People" AS t1 LEFT JOIN "TodoItems" AS t2 ON t1."Id" = t2."OwnerId" - ORDER BY t1."Id", ( + ORDER BY ( SELECT COUNT(*) FROM "Tags" AS t3 WHERE t2."Id" = t3."TodoItemId" @@ -263,7 +262,7 @@ SELECT COUNT(*) FROM "People" AS t1 LEFT JOIN "TodoItems" AS t2 ON t1."Id" = t2."OwnerId" LEFT JOIN "Tags" AS t4 ON t2."Id" = t4."TodoItemId" - ORDER BY t1."Id", ( + ORDER BY ( SELECT COUNT(*) FROM "Tags" AS t3 WHERE t2."Id" = t3."TodoItemId" @@ -326,11 +325,11 @@ SELECT COUNT(*) SELECT COUNT(*) FROM "Tags" AS t4 WHERE t3."Id" = t4."TodoItemId" - ), t5."Id", ( + ), ( SELECT COUNT(*) FROM "Tags" AS t7 WHERE t6."Id" = t7."TodoItemId" - ), t8."Id" + ) """)); command.Parameters.Should().BeEmpty(); @@ -383,7 +382,7 @@ LEFT JOIN ( FROM "TodoItems" AS t2 WHERE t2."Description" = @p1 ) AS t3 ON t1."Id" = t3."OwnerId" - ORDER BY t1."Id", t3."Priority", t3."LastModifiedAt" DESC + ORDER BY t3."Priority", t3."LastModifiedAt" DESC """)); command.Parameters.Should().HaveCount(1); @@ -441,7 +440,7 @@ SELECT 1 WHERE t2."Id" = t3."TodoItemId" ) ) AS t4 ON t1."Id" = t4."OwnerId" - ORDER BY t1."Id", t4."Priority", t4."LastModifiedAt" DESC + ORDER BY t4."Priority", t4."LastModifiedAt" DESC """)); command.Parameters.Should().BeEmpty(); @@ -498,7 +497,7 @@ SELECT COUNT(*) WHERE t2."Id" = t3."TodoItemId" ) > @p1 ) AS t4 ON t1."Id" = t4."OwnerId" - ORDER BY t1."Id", t4."Priority", t4."LastModifiedAt" DESC + ORDER BY t4."Priority", t4."LastModifiedAt" DESC """)); command.Parameters.Should().HaveCount(1); @@ -554,7 +553,7 @@ LEFT JOIN ( LEFT JOIN "Tags" AS t4 ON t2."Id" = t4."TodoItemId" WHERE t2."Description" = @p1 ) AS t5 ON t1."Id" = t5."OwnerId" - ORDER BY t1."Id", ( + ORDER BY ( SELECT COUNT(*) FROM "Tags" AS t3 WHERE t5."Id" = t3."TodoItemId" @@ -620,7 +619,7 @@ WHERE NOT (t5."Name" = @p2) ) AS t6 ON t2."Id" = t6."TodoItemId" WHERE NOT (t2."Description" = @p1) ) AS t7 ON t1."Id" = t7."OwnerId" - ORDER BY t1."Id", ( + ORDER BY ( SELECT COUNT(*) FROM "Tags" AS t3 WHERE t7."Id" = t3."TodoItemId" From 3c6d3bebe0beedadcf8a3fcb89c83b63fbbb8076 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Wed, 4 Jun 2025 00:44:55 +0200 Subject: [PATCH 12/17] Throw when AddOpenApiForJsonApi is called before AddJsonApi (#1737) --- .../ServiceCollectionExtensions.cs | 10 ++++++++ .../IncorrectSetupOrder/RegistrationTests.cs | 24 +++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 test/OpenApiTests/OpenApiGenerationFailures/IncorrectSetupOrder/RegistrationTests.cs diff --git a/src/JsonApiDotNetCore.OpenApi.Swashbuckle/ServiceCollectionExtensions.cs b/src/JsonApiDotNetCore.OpenApi.Swashbuckle/ServiceCollectionExtensions.cs index 3b421c31d..687211528 100644 --- a/src/JsonApiDotNetCore.OpenApi.Swashbuckle/ServiceCollectionExtensions.cs +++ b/src/JsonApiDotNetCore.OpenApi.Swashbuckle/ServiceCollectionExtensions.cs @@ -1,4 +1,5 @@ using JsonApiDotNetCore.Configuration; +using JsonApiDotNetCore.Errors; using JsonApiDotNetCore.Middleware; using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiMetadata; using JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators; @@ -23,6 +24,7 @@ public static class ServiceCollectionExtensions public static void AddOpenApiForJsonApi(this IServiceCollection services, Action? configureSwaggerGenOptions = null) { ArgumentNullException.ThrowIfNull(services); + AssertHasJsonApi(services); AddCustomApiExplorer(services); AddCustomSwaggerComponents(services); @@ -38,6 +40,14 @@ public static void AddOpenApiForJsonApi(this IServiceCollection services, Action services.Replace(ServiceDescriptor.Singleton()); } + private static void AssertHasJsonApi(IServiceCollection services) + { + if (services.FirstOrDefault(descriptor => descriptor.ServiceType == typeof(IJsonApiOptions)) == null) + { + throw new InvalidConfigurationException("Call 'services.AddJsonApi()' before calling 'services.AddOpenApiForJsonApi()'."); + } + } + private static void AddCustomApiExplorer(IServiceCollection services) { services.TryAddSingleton(); diff --git a/test/OpenApiTests/OpenApiGenerationFailures/IncorrectSetupOrder/RegistrationTests.cs b/test/OpenApiTests/OpenApiGenerationFailures/IncorrectSetupOrder/RegistrationTests.cs new file mode 100644 index 000000000..603310008 --- /dev/null +++ b/test/OpenApiTests/OpenApiGenerationFailures/IncorrectSetupOrder/RegistrationTests.cs @@ -0,0 +1,24 @@ +using FluentAssertions; +using JsonApiDotNetCore.Errors; +using JsonApiDotNetCore.OpenApi.Swashbuckle; +using Microsoft.Extensions.DependencyInjection; +using Xunit; + +namespace OpenApiTests.OpenApiGenerationFailures.IncorrectSetupOrder; + +public sealed class RegistrationTests +{ + [Fact] + public void Fails_when_OpenAPI_registered_without_JsonApi() + { + // Arrange + var services = new ServiceCollection(); + + // Act + Action action = () => services.AddOpenApiForJsonApi(); + + // Arrange + action.Should().ThrowExactly() + .WithMessage("Call 'services.AddJsonApi()' before calling 'services.AddOpenApiForJsonApi()'."); + } +} From e02db08ae14480a250bda355bdc978f08abfc391 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sat, 14 Jun 2025 00:28:53 +0200 Subject: [PATCH 13/17] Package updates (#1740) --- .config/dotnet-tools.json | 2 +- package-versions.props | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index f14a93f95..9d271bea8 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -31,7 +31,7 @@ "rollForward": false }, "microsoft.openapi.kiota": { - "version": "1.25.1", + "version": "1.27.0", "commands": [ "kiota" ], diff --git a/package-versions.props b/package-versions.props index 0403a83c0..0f2c3f6e7 100644 --- a/package-versions.props +++ b/package-versions.props @@ -4,11 +4,11 @@ 4.1.0 0.4.1 2.14.1 - 8.0.0 + 9.0.1 13.0.3 - 0.14.* + 0.15.* 1.0.* 35.6.* 4.14.* @@ -23,12 +23,12 @@ 14.4.* 13.0.* 4.1.* - 2.3.* - 8.*-* + 2.4.* + 9.*-* 9.0.* 17.14.* 2.9.* - 2.8.* + 3.1.* From 8877a58f50b8b57b3313702f35b86aad46a3187b Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sat, 14 Jun 2025 01:16:20 +0200 Subject: [PATCH 14/17] Remove kiota limitation from list of known issues (the bug was fixed) --- docs/usage/openapi-client.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/usage/openapi-client.md b/docs/usage/openapi-client.md index 277d28021..5dc40ce6f 100644 --- a/docs/usage/openapi-client.md +++ b/docs/usage/openapi-client.md @@ -341,7 +341,6 @@ demonstrates how to use them. It uses local IDs to: | Properties are always nullable | - | https://github.com/microsoft/kiota/issues/3911 | | JSON:API query strings are inaccessible | Use `SetQueryStringHttpMessageHandler.CreateScope` from `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/3800 | | HTTP 304 (Not Modified) is not properly recognized | Catch `ApiException` and inspect the response status code | https://github.com/microsoft/kiota/issues/4190, https://github.com/microsoft/kiota-dotnet/issues/531 | -| No `Accept` header sent when only error responses define `Content-Type` | `JsonApiDotNetCore.OpenApi.Swashbuckle` package contains workaround | https://github.com/microsoft/kiota/issues/6572 | | Generator warns about unsupported formats | Use `JsonApiDotNetCore.OpenApi.Client.Kiota` package | https://github.com/microsoft/kiota/issues/4227 | | `Stream` response for HEAD request | - | https://github.com/microsoft/kiota/issues/4245 | | Unhelpful exception messages | - | https://github.com/microsoft/kiota/issues/4349 | From b438837feb1698559adbde5ee982b8134f1ad46a Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sun, 15 Jun 2025 00:36:23 +0200 Subject: [PATCH 15/17] Update VERSIONING_POLICY.md Remove references to types that no longer exist. --- VERSIONING_POLICY.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/VERSIONING_POLICY.md b/VERSIONING_POLICY.md index d44770cfc..a32ee43d7 100644 --- a/VERSIONING_POLICY.md +++ b/VERSIONING_POLICY.md @@ -1,8 +1,8 @@ # JsonApiDotNetCore versioning policy -Basically, we strive to adhere to [semantic versioning](https://semver.org/). +Basically, we strive to adhere to [Semantic Versioning](https://semver.org/). -However, we believe that our userbase is still small enough to allow for some flexibility in _minor_ updates, see below. +However, we believe that our user base is still small enough to allow for some flexibility in _minor_ updates, see below. ## Major updates @@ -10,9 +10,9 @@ For breaking changes in _major_ updates, we intend to list the ones that may aff ## Minor updates -We **WILL NOT** introduce breaking changes in _minor_ updates on our common extensibility points such as controllers, resource services, resource repositories, resource definitions, and `Identifiable` as well as common annotations such as `[Attr]`, `[HasOne]`, `[HasMany]`, and `[HasManyThrough]`. The same applies to the URL routes, JSON structure of request/response bodies, and query string syntax. +We **WILL NOT** introduce breaking changes in _minor_ updates on our common extensibility points, such as controllers, resource services, resource repositories, resource definitions, and `Identifiable`, as well as common annotations, such as `[Attr]`, `[HasOne]`, and `[HasMany]`. The same applies to the URL routes, JSON structure of request and response bodies, and query string syntax. -In previous versions of JsonApiDotNetCore, almost everything was public. While that makes customizations very easy for users, it kinda puts us in a corner: nearly every change would require a new major version. Therefore we try to balance between adding new features to the next _minor_ version or postpone them to the next _major_ version. This means we **CAREFULLY CONSIDER** if we can prevent breaking changes in _minor_ updates to signatures of "pubternal" types (public types in `Internal` namespaces), as well as exposed types of which we believe users are unlikely to have taken a direct dependency on. One example would be to inject an additional dependency in the constructor of a not-so-well-known class, such as `IncludedResourceObjectBuilder`. In the unlikely case that a user has taken a dependency on this class, the compiler error message is clear and the fix is obvious and easy. We may introduce binary breaking changes (such as adding an optional constructor parameter to a custom exception type), which requires users to recompile their existing code. +In previous versions of JsonApiDotNetCore, almost everything was public. While that makes customizations very easy for users, it kinda puts us in a corner: nearly every change would require a new major version. Therefore, we try to balance between adding new features to the next _minor_ version or postponing them to the next _major_ version. This means we **CAREFULLY CONSIDER** if we can prevent breaking changes in _minor_ updates to signatures of "pubternal" types (public types in `Internal` namespaces), as well as exposed types of which we believe users are unlikely to have taken a direct dependency on. One example would be to inject an additional dependency in the constructor of a not-so-well-known class, such as `OperationsProcessor`. In the unlikely case that a user has taken a dependency on this class, the compiler error message is clear, and the fix is obvious and easy. We may introduce binary breaking changes (such as adding an optional constructor parameter to a custom exception type), which requires users to recompile their existing code. Our goal is to try to minimize such breaks and require only a recompile of existing API projects. This also means that we'll need to publish an updated release for [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb) when this happens. @@ -20,4 +20,4 @@ We may also correct error messages in _minor_ updates. ## Backports -When users report that they are unable to upgrade as a result of breaking changes in a _minor_ version, we're willing to consider backporting fixes they need to an earlier _minor_ version. +When users report that they're unable to upgrade as a result of breaking changes in a _minor_ version, we're willing to consider backporting fixes they need to an earlier _minor_ version. From 1beae23ab605a12697fa1c611d0bd83864c1bca2 Mon Sep 17 00:00:00 2001 From: Bart Koelman <10324372+bkoelman@users.noreply.github.com> Date: Sat, 28 Jun 2025 13:47:28 +0200 Subject: [PATCH 16/17] Update JetBrains logo (#1741) --- README.md | 19 +++++++++++++++---- docs/home/assets/home.js | 2 +- docs/home/assets/img/jetbrains-logo-dark.svg | 13 +++++++++++++ docs/home/assets/img/jetbrains-logo-light.svg | 13 +++++++++++++ docs/home/index.html | 6 +++++- 5 files changed, 47 insertions(+), 6 deletions(-) create mode 100644 docs/home/assets/img/jetbrains-logo-dark.svg create mode 100644 docs/home/assets/img/jetbrains-logo-light.svg diff --git a/README.md b/README.md index 5ab49fae3..dc8d5579b 100644 --- a/README.md +++ b/README.md @@ -287,9 +287,20 @@ pwsh Build.ps1 ## Sponsors -We are very grateful to the sponsors below, who have provided us with a no-cost license for their tools. - -

+We are grateful to the following sponsors, who provide the team with a no-cost license for using their tools. + +

+ + + + + + + + + + + +

Do you like this project? Consider to [sponsor](https://github.com/sponsors/json-api-dotnet), or just reward us by giving our repository a star. diff --git a/docs/home/assets/home.js b/docs/home/assets/home.js index 40e31c15a..3288b5647 100644 --- a/docs/home/assets/home.js +++ b/docs/home/assets/home.js @@ -83,7 +83,7 @@ function initTheme() { } // Sponsor panels linking - $('div[sponsor]#jetbrains').on('click', () => navigateExternalTo('https://jb.gg/OpenSourceSupport')); + $('div[sponsor]#jetbrains').on('click', () => navigateExternalTo('https://www.jetbrains.com/community/opensource')); $('div[sponsor]#araxis').on('click', () => navigateExternalTo('https://www.araxis.com/buy/open-source')); const navigateExternalTo = (url) => { diff --git a/docs/home/assets/img/jetbrains-logo-dark.svg b/docs/home/assets/img/jetbrains-logo-dark.svg new file mode 100644 index 000000000..6c68019bf --- /dev/null +++ b/docs/home/assets/img/jetbrains-logo-dark.svg @@ -0,0 +1,13 @@ + diff --git a/docs/home/assets/img/jetbrains-logo-light.svg b/docs/home/assets/img/jetbrains-logo-light.svg new file mode 100644 index 000000000..cb3a2a0e5 --- /dev/null +++ b/docs/home/assets/img/jetbrains-logo-light.svg @@ -0,0 +1,13 @@ + diff --git a/docs/home/index.html b/docs/home/index.html index a8530ec89..4b3294631 100644 --- a/docs/home/index.html +++ b/docs/home/index.html @@ -303,7 +303,11 @@

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Includes support for the Atomic Operations extension.

Sponsors

Sponsors

Sponsors

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.