repository·master·Indexed 20 days ago
https://github.com/json-api-dotnet/jsonapidotnetcoreA framework for building JSON:API compliant REST APIs using ASP.NET Core and Entity Framework Core. It provides built-in support for sorting, filtering, pagination, sparse fieldsets, and side-loading to minimize boilerplate. The documentation covers resource definition using attributes like [Resource] and [Attr], request pipeline management via JsonApiController, query string parsing, and integration with OpenAPI via the openapi:discriminator extension.
Soft deletion and Archiving are similar patterns in JsonApiDotNetCore, but they differ in visibility:
When deciding between Archiving and Soft Deletion in JsonApiDotNetCore, use the following mental model:
| Feature | Client Accessibility | Use Case |
|---|---|---|
| Archiving | Accessible via ID, hidden from searches | Hiding items from general lists without losing the ability to reference them directly. |
| Soft Deletion | Never accessible to JSON:API clients | Removing items from the system entirely while retaining them in the database for audit/recovery. |
The JSON:API Extension for OpenAPI is designed to improve the effectiveness of OpenAPI client generators when working with JSON:API documents.
Standard OpenAPI can use allOf inheritance and a discriminator property for the top-level data member, but it cannot natively express that discriminators should recursively apply to nested objects within attributes and relationships. This extension solves that by introducing an openapi:discriminator property that guides code generation tools to correctly identify types for nested structures.
In a multi-tenant system, not every table needs a TenantId column. If a resource (e.g., WebProduct) has a foreign key to a tenant-specific resource (e.g., WebShop), the tenant isolation is maintained through the relationship chain.
When querying the related resource, the HasQueryFilter applied to the parent resource (the one with the TenantId) ensures that only products belonging to the tenant's specific shops are returned, even if the products themselves do not explicitly store a TenantId.
Both NSwag and Kiota generated clients fully support Atomic operations. This allows you to group multiple operations (like creating a tag and a person, then linking them) into a single request to ensure consistency.
TrackChangesFor from the JsonApiDotNetCore.OpenApi.Client.NSwag package to handle attribute clearing during updates.JsonApiDotNetCore follows Semantic Versioning (SemVer) with some flexibility regarding minor updates to balance feature velocity with stability.
Major updates contain breaking changes that may affect user code or API clients. These changes are documented in the release notes and official documentation.
To avoid frequent major version bumps, the project may introduce minor breaking changes in specific areas. However, the following core components are guaranteed to remain stable (no breaking changes) in minor updates:
Identifiable interface.[Attr], [HasOne], and [HasMany].Note on 'Pubternal' types: The project may introduce breaking changes to types in Internal namespaces or less common classes (e.g., OperationsProcessor) during minor updates. These changes might be binary-breaking (e.g., adding an optional constructor parameter), which requires you to recompile your existing code to resolve compiler errors. If you use these types, expect to recompile your project during minor version upgrades.
Content negotiation in JsonApiDotNetCore allows the server to support specific JSON:API extensions based on the Accept and Content-Type HTTP headers. This is achieved through a coordinated flow across several extensibility points:
JsonApiOptions during application startup to make them available to the framework.JsonApiContentNegotiator evaluates the incoming request's headers to determine which extensions are active for that specific request.IDocumentAdapter is used to intercept and capture specific properties from the incoming request body (such as values inside the top-level meta object).IResponseMeta implementation uses the information from the active extensions and the captured request data to inject additional data into the top-level meta of the JSON:API response.ObfuscatedIdentifiable and your controller inherits from ObfuscatedIdentifiableController. This ensures that the id parameters in your controller actions are treated as string types, allowing the framework to handle the de-obfuscation of the incoming client string into the internal numeric ID.Resource definitions provide a way to intercept and modify JSON:API queries before they are executed. By inheriting from JsonApiResourceDefinition<TResource, TId>, you can override specific methods to manipulate the query.
Instead of working directly with Entity Framework Core IQueryable, you work with an intermediate format (such as QueryExpression, SortExpression, PaginationExpression, etc.). This abstraction separates the JSON:API protocol implementation from the underlying database execution.
Common customization points include:
Password field for non-admins).JsonApiException.JsonApiDotNetCore processes incoming JSON:API requests through a multi-stage pipeline that transforms HTTP query strings into optimized SQL via Entity Framework Core.
JsonApiMiddleware identifies resource information from routing.IQueryStringParameterReader uses QueryParser to convert query string text into QueryExpression objects. It uses prefix notation for filters (e.g., and(equals(a, b), c)) to avoid operator precedence issues.QueryLayerComposer (via JsonApiResourceService) gathers constraints, applies default options and IResourceDefinition overrides, and builds a tree of QueryLayer objects. This stage handles secondary endpoints (e.g., /blogs/1/articles) and rewrites includes.EntityFrameworkCoreRepository uses a QueryableBuilder to transform the QueryLayer tree into LINQ IQueryable expression trees.JsonApiWriter converts the resulting resource objects back into a JSON:API compliant response.When a resource has a calculated property that depends on related data, use the [EagerLoad] attribute on the relationship to ensure the necessary data is fetched from the database.
Important Behavior: Even when using [EagerLoad], the related resources are not returned in the JSON response to the client unless the client explicitly requests them using the include query string parameter. The attribute's purpose is to optimize database fetching for internal logic, not to change the default JSON output structure.
// Example pattern for a calculated property depending on a relationship
public class Street
{
// The DoorTotalCount property depends on Buildings
[EagerLoad]
public ICollection<Building> Buildings { get; set; }
public int DoorTotalCount => Buildings.Count; // Calculated property
}