-
+
+
+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/ROADMAP.md b/ROADMAP.md
index 536bda5ea3..d73797824f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -2,31 +2,18 @@
This document provides an overview of the direction this project is heading and lists what we intend to work on in the near future.
-> Disclaimer: This is an open source project. The available time of our contributors varies and therefore we do not plan release dates. This document expresses our current intent, which may change over time.
-
-## v4.x
-In December 2020, we released v4.0 stable after a long time. From now on, we'd like to release new features and bugfixes often.
-In subsequent v4.x releases, we intend to implement the next features in non-breaking ways.
-
-- Codebase improvements (refactor tests [#715](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/715), coding guidelines [#835](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/835) [#290](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/290), cibuild [#908](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/908))
-- Bulk/batch support (atomic:operations) [#936](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/936)
-- Write callbacks [#934](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/934)
-- ETags [#933](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/933)
-- Optimistic Concurrency [#350](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/350)
-- Configuration validation [#414](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/414) [#170](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/170)
-
-## vNext
-We have interest in the following topics for future versions.
-Some cannot be done in v4.x the way we'd like without introducing breaking changes.
-Others require more exploration first, or depend on other features.
-
-- Resource inheritance [#844](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/844)
-- Split into multiple NuGet packages [#730](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/730) [#661](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/661) [#292](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/292)
-- System.Text.Json [#664](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/664)
-- EF Core 5 Many-to-many relationships [#935](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/935)
+> Disclaimer: This is an open-source project. The available time of our contributors varies and therefore we do not plan release dates. This document expresses our current intent, which may change over time.
+
+We have an interest in the following topics. It's too soon yet to decide whether they'll make it into v5.x or in a later major version.
+
+- Provide additional OpenAPI support [#1046](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1046)
+- Query strings on JSON-mapped columns [#1439](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1439)
+- Improved resource inheritance [#1642](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1642)
+- Improved SQL Server support [#1118](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1118)
+- Use incremental source generator [#1447](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/1447)
+- Optimistic concurrency [#1119](https://github.com/json-api-dotnet/JsonApiDotNetCore/pull/1119)
+- Idempotency [#1132](https://github.com/json-api-dotnet/JsonApiDotNetCore/pull/1132)
- Fluent API [#776](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/776)
-- Auto-generated controllers [#732](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/732) [#365](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/365)
-- Serialization, discovery and documentation [#661](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/661) [#259](https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/259)
## Feedback
@@ -36,3 +23,5 @@ Please give us feedback that will give us insight on the following points:
* Existing features that are missing some capability or otherwise don't work well enough.
* Missing features that should be added to the product.
* Design choices for a feature that is currently in-progress.
+
+Please consider to [sponsor the project](https://github.com/sponsors/json-api-dotnet).
diff --git a/VERSIONING_POLICY.md b/VERSIONING_POLICY.md
index d44770cfcc..a32ee43d7d 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.
diff --git a/WarningSeverities.DotSettings b/WarningSeverities.DotSettings
index f4a9ae32e8..5b64971520 100644
--- a/WarningSeverities.DotSettings
+++ b/WarningSeverities.DotSettings
@@ -1,4 +1,5 @@
+
+
+
+ JsonApiDotNetCore documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ JsonApiDotNetCore
++ A framework for building JSON:API compliant REST APIs using ASP.NET Core and Entity Framework Core. + Includes support for the Atomic Operations extension. +
+ Read more + Getting started + Contribute on GitHub +
+ 
+
+
+
+
+
+
-
-
+
+ 
+
+
+
+
-
- Objectives
++ The goal of this library is to simplify the development of APIs that leverage the full range of features + provided by the JSON:API specification. + You just need to focus on defining the resources and implementing your custom business logic. +
-
-
-
- JsonApiDotNetCore
-A framework for building JSON:API compliant REST APIs using .NET Core and Entity Framework Core. Includes support for Atomic Operations.
- Read more - Getting started - Contribute on GitHub -
- 
-
+
-
+
+
+ Eliminate boilerplate
++ The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features, such as sorting, filtering, pagination, sparse fieldset selection, and side-loading related resources. +
+
+
+
Extensibility
+This library has been designed around dependency injection, making extensibility incredibly easy.
+
-
+
-
+
-
-
-
-
-
- Objectives
-- The goal of this library is to simplify the development of APIs that leverage the full range of features provided by the JSON:API specification. - You just need to focus on defining the resources and implementing your custom business logic. -
-
-
-
-
-
- Eliminate boilerplate
-We strive to eliminate as much boilerplate as possible by offering out-of-the-box features such as sorting, filtering and pagination.
-
-
-
- Extensibility
-This library has been designed around dependency injection, making extensibility incredibly easy.
-
+
+
+ Features
+The following features are supported, from HTTP all the way down to the database
+
+
+
-
-
-
+
-
-
+
Filtering
+Perform compound filtering using the filter query string parameter
-
-
-
- Features
-The following features are supported, from HTTP all the way down to the database
-
-
-
-
-
-
-
-
Filtering
-Perform compound filtering using the filter query string parameter
-
-
-
-
-
Sorting
-Order resources on one or multiple attributes using the sort query string parameter
-
-
-
-
-
Pagination
-Leverage the benefits of paginated resources with the page query string parameter
-
-
-
-
-
Sparse fieldset selection
-Get only the data that you need using the fields query string parameter
-
-
-
-
-
-
-
Relationship inclusion
-Side-load related resources of nested relationships using the include query string parameter
-
-
-
-
-
Security
-Configure permissions, such as view/create/change/sort/filter of attributes and relationships
-
-
-
-
-
-
Validation
-Validate incoming requests using built-in ASP.NET Core ModelState validation, which works seamlessly with partial updates
-
-
-
-
-
Customizable
-Use various extensibility points to intercept and run custom code, besides just model annotations
-
-
-
+ Example usage
-Expose resources with attributes and relationships
+
+
+
+
+
+
-
+
Sorting
+Order resources on multiple attributes using the sort query string parameter
-
+
+
-
+
-
+
-
Resource
-
-public class Article : Identifiable
+
+
+
+
+
+
Pagination
+Leverage the benefits of paginated resources with the page query string parameter
+
+
+
+
+
Sparse fieldset selection
+Get only the data that you need using the fields query string parameter
+
+
+
+
+
+
+
Relationship inclusion
+Side-load related resources of nested relationships using the include query string parameter
+
+
+
+
+
Security
+Configure permissions, such as viewing, creating, modifying, sorting and filtering of attributes and relationships
+
+
+
+
+
+
Validation
+Validate incoming requests using built-in ASP.NET Model Validation, which works seamlessly with partial updates
+
+
+
+
+
+
Customizable
+Use various extensibility points to intercept and run custom code, besides just model annotations
+
+
+
+
+ Example usage
+Expose resources with attributes and relationships
+
+
-
+
+
+
-
+
Resource
+
+#nullable enable
+
+public class Article : Identifiable<long>
{
[Attr]
- [Required, MaxLength(30)]
- public string Title { get; set; }
+ [MaxLength(30)]
+ public string Title { get; set; } = null!;
[Attr(Capabilities = AttrCapabilities.AllowFilter)]
- public string Summary { get; set; }
+ public string? Summary { get; set; }
[Attr(PublicName = "websiteUrl")]
- public string Url { get; set; }
+ public string? Url { get; set; }
+
+ [Attr]
+ [Required]
+ public int? WordCount { get; set; }
[Attr(Capabilities = AttrCapabilities.AllowView)]
public DateTimeOffset LastModifiedAt { get; set; }
[HasOne]
- public Person Author { get; set; }
+ public Person Author { get; set; } = null!;
- [HasMany]
- public ICollection<Revision> Revisions { get; set; }
+ [HasOne]
+ public Person? Reviewer { get; set; }
- [HasManyThrough(nameof(ArticleTags))]
- [NotMapped]
- public ICollection<Tag> Tags { get; set; }
- public ICollection<ArticleTag> ArticleTags { get; set; }
+ [HasMany]
+ public ICollection<Tag> Tags { get; set; } = new HashSet<Tag>();
}
-
-
-
+
-
+
-
-
-
Request
-
-
-GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author HTTP/1.1
-
-
-
+
+
+
+
+
-
+
Request
+GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields[articles]=title,summary&include=author HTTP/1.1
-
+
-
+
-
+
-
Response
-
-
-{
+
+
+
+
+
+
+
-
+
Response
+
+{
"meta": {
"totalResources": 1
},
"links": {
- "self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author",
- "first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author",
- "last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author"
+ "self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
+ "first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
+ "last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author"
},
"data": [
{
@@ -248,31 +288,54 @@ Response
]
}
-
-
+
+
+ Sponsors
+
+
+
-
-
+
-
+
+
+