Class JsonApiResourceDefinition<TResource, TId>

Provides an extensibility point to add business logic that is resource-oriented instead of endpoint-oriented.

Inheritance

System.Object

JsonApiResourceDefinition<TResource, TId>

Implements

IResourceDefinition<TResource, TId>

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: JsonApiDotNetCore.Resources

Assembly: JsonApiDotNetCore.dll

Syntax

[PublicAPI]
public class JsonApiResourceDefinition<TResource, TId> : IResourceDefinition<TResource, TId> where TResource : class, IIdentifiable<TId>

Type Parameters

Name	Description
TResource	The resource type.
TId	The resource identifier type.

Constructors

| Improve this Doc View Source

JsonApiResourceDefinition(IResourceGraph)

Declaration

public JsonApiResourceDefinition(IResourceGraph resourceGraph)

Parameters

Type	Name	Description
IResourceGraph	resourceGraph

Properties

| Improve this Doc View Source

ResourceGraph

Declaration

protected IResourceGraph ResourceGraph { get; }

Property Value

Type	Description
IResourceGraph

| Improve this Doc View Source

ResourceType

Provides metadata for the resource type TResource.

Declaration

protected ResourceType ResourceType { get; }

Property Value

Type	Description
ResourceType

Methods

| Improve this Doc View Source

CreateSortExpressionFromLambda(JsonApiResourceDefinition<TResource, TId>.PropertySortOrder)

Creates a SortExpression from a lambda expression.

Declaration

protected SortExpression CreateSortExpressionFromLambda(JsonApiResourceDefinition<TResource, TId>.PropertySortOrder keySelectors)

Parameters

Type	Name	Description
JsonApiResourceDefinition.PropertySortOrder<>	keySelectors

Returns

Type	Description
SortExpression

Examples

var sort = CreateSortExpressionFromLambda(new PropertySortOrder
{
    (blog => blog.Author.Name.LastName, ListSortDirection.Ascending),
    (blog => blog.Posts.Count, ListSortDirection.Descending),
    (blog => blog.Title, ListSortDirection.Ascending)
});

| Improve this Doc View Source

GetMeta(TResource)

Enables to add JSON:API meta information, specific to this resource.

Declaration

public virtual IDictionary<string, object>? GetMeta(TResource resource)

Parameters

Type	Name	Description
TResource	resource

Returns

Type	Description
System.Nullable<IDictionary<System.String, System.Object>>

| Improve this Doc View Source

OnAddToRelationshipAsync(TResource, HasManyAttribute, ISet<IIdentifiable>, CancellationToken)

Executes before adding resources to the right side of a to-many relationship, as part of a POST relationship request.

Implementing this method enables to perform validations and make changes to rightResourceIds, before the relationship is updated.

Declaration

public virtual Task OnAddToRelationshipAsync(TResource leftResource, HasManyAttribute hasManyRelationship, ISet<IIdentifiable> rightResourceIds, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	leftResource	Identifier of the left resource. The indication "left" specifies that `hasManyRelationship` is declared on `TResource`. In contrast to other relationship methods, this value is not retrieved from the underlying data store, except in the following two cases: `hasManyRelationship` is a many-to-many relationship. This is required to prevent failure when already assigned. The left resource type is part of a type hierarchy. This ensures your business logic runs against the actually stored type.
HasManyAttribute	hasManyRelationship	The to-many relationship being added to.
ISet<IIdentifiable>	rightResourceIds	The set of resource identifiers to add to the to-many relationship, coming from the request.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task

| Improve this Doc View Source

OnApplyFilter(FilterExpression)

Enables to extend, replace or remove a filter that is being applied on a set of this resource type.

Declaration

public virtual FilterExpression OnApplyFilter(FilterExpression existingFilter)

Parameters

Type	Name	Description
FilterExpression	existingFilter	An optional existing filter, coming from query string. Can be `null`.

Returns

Type	Description
FilterExpression	The new filter, or `null` to disable the existing filter.

| Improve this Doc View Source

OnApplyIncludes(IImmutableSet<IncludeElementExpression>)

Enables to extend, replace or remove includes that are being applied on this resource type.

Declaration

public virtual IImmutableSet<IncludeElementExpression> OnApplyIncludes(IImmutableSet<IncludeElementExpression> existingIncludes)

Parameters

Type	Name	Description
System.Collections.Immutable.IImmutableSet<IncludeElementExpression>	existingIncludes	An optional existing set of includes, coming from query string. Never `null`, but may be empty.

Returns

Type	Description
System.Collections.Immutable.IImmutableSet<IncludeElementExpression>	The new set of includes. Return an empty collection to remove all inclusions (never return `null`).

| Improve this Doc View Source

OnApplyPagination(PaginationExpression)

Enables to extend, replace or remove pagination that is being applied on a set of this resource type.

Declaration

public virtual PaginationExpression OnApplyPagination(PaginationExpression existingPagination)

Parameters

Type	Name	Description
PaginationExpression	existingPagination	An optional existing pagination, coming from query string. Can be `null`.

Returns

Type	Description
PaginationExpression	The changed pagination, or `null` to use the first page with default size from options. To disable paging, set PageSize to `null`.

| Improve this Doc View Source

OnApplySort(SortExpression)

Enables to extend, replace or remove a sort order that is being applied on a set of this resource type. Tip: Use CreateSortExpressionFromLambda(JsonApiResourceDefinition<TResource, TId>.PropertySortOrder) to build from a lambda expression.

Declaration

public virtual SortExpression OnApplySort(SortExpression existingSort)

Parameters

Type	Name	Description
SortExpression	existingSort	An optional existing sort order, coming from query string. Can be `null`.

Returns

Type	Description
SortExpression	The new sort order, or `null` to disable the existing sort order and sort by ID.

| Improve this Doc View Source

OnApplySparseFieldSet(SparseFieldSetExpression)

Enables to extend, replace or remove a sparse fieldset that is being applied on a set of this resource type. Tip: Use Including<TResource>(SparseFieldSetExpression, Expression<Func<TResource, Object>>, IResourceGraph) and Excluding<TResource>(SparseFieldSetExpression, Expression<Func<TResource, Object>>, IResourceGraph) to safely change the fieldset without worrying about nulls.

Declaration

public virtual SparseFieldSetExpression OnApplySparseFieldSet(SparseFieldSetExpression existingSparseFieldSet)

Parameters

Type	Name	Description
SparseFieldSetExpression	existingSparseFieldSet	The incoming sparse fieldset from query string. At query execution time, this is `null` if the query string contains no sparse fieldset. At serialization time, this contains all viewable fields if the query string contains no sparse fieldset.

Returns

Type	Description
SparseFieldSetExpression	The new sparse fieldset, or `null` to discard the existing sparse fieldset and select all viewable fields.

Remarks

This method executes twice for a single request: first to select which fields to retrieve from the data store and then to select which fields to serialize. Including extra fields from this method will retrieve them, but not include them in the json output. This enables you to expose calculated properties whose value depends on a field that is not in the sparse fieldset.

| Improve this Doc View Source

OnDeserialize(TResource)

Executes after a resource has been deserialized from an incoming request body.

Declaration

public virtual void OnDeserialize(TResource resource)

Parameters

Type	Name	Description
TResource	resource	The deserialized resource.

| Improve this Doc View Source

OnPrepareWriteAsync(TResource, WriteOperationKind, CancellationToken)

Executes after the original version of the resource has been retrieved from the underlying data store, as part of a write request.

Implementing this method enables to perform validations and make changes to resource, before the fields from the request are copied into it.

For POST resource requests, this method is typically used to assign property default values or to set required relationships by side-loading the related resources and linking them.

Declaration

public virtual Task OnPrepareWriteAsync(TResource resource, WriteOperationKind writeOperation, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	resource	The original resource retrieved from the underlying data store, or a freshly instantiated resource in case of a POST resource request.
WriteOperationKind	writeOperation	Identifies the logical write operation for which this method was called. Possible values: CreateResource, UpdateResource, SetRelationship and RemoveFromRelationship. Note this intentionally excludes DeleteResource and AddToRelationship, because for those endpoints no resource is retrieved upfront.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task

| Improve this Doc View Source

OnRegisterQueryableHandlersForQueryStringParameters()

Enables to adapt the Entity Framework Core query, based on custom query string parameters. Note this only works on primary resource requests, such as /articles, but not on /blogs/1/articles or /blogs?include=articles.

Declaration

public virtual QueryStringParameterHandlers<TResource> OnRegisterQueryableHandlersForQueryStringParameters()

Returns

Type	Description
QueryStringParameterHandlers<TResource>

| Improve this Doc View Source

OnRemoveFromRelationshipAsync(TResource, HasManyAttribute, ISet<IIdentifiable>, CancellationToken)

Executes before removing resources from the right side of a to-many relationship, as part of a DELETE relationship request.

Implementing this method enables to perform validations and make changes to rightResourceIds, before the relationship is updated.

Declaration

public virtual Task OnRemoveFromRelationshipAsync(TResource leftResource, HasManyAttribute hasManyRelationship, ISet<IIdentifiable> rightResourceIds, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	leftResource	The original resource as retrieved from the underlying data store. The indication "left" specifies that `hasManyRelationship` is declared on `TResource`. Be aware that for performance reasons, not the full relationship is populated, but only the subset of resources to be removed.
HasManyAttribute	hasManyRelationship	The to-many relationship being removed from.
ISet<IIdentifiable>	rightResourceIds	The set of resource identifiers to remove from the to-many relationship, coming from the request.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task

| Improve this Doc View Source

OnSerialize(TResource)

Executes before a (primary or included) resource is serialized into an outgoing response body.

Declaration

public virtual void OnSerialize(TResource resource)

Parameters

Type	Name	Description
TResource	resource	The serialized resource.

| Improve this Doc View Source

OnSetToManyRelationshipAsync(TResource, HasManyAttribute, ISet<IIdentifiable>, WriteOperationKind, CancellationToken)

Executes before setting the resources at the right side of a to-many relationship. This replaces on existing set.

Implementing this method enables to perform validations and make changes to rightResourceIds, before the relationship is updated.

Declaration

public virtual Task OnSetToManyRelationshipAsync(TResource leftResource, HasManyAttribute hasManyRelationship, ISet<IIdentifiable> rightResourceIds, WriteOperationKind writeOperation, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	leftResource	The original resource as retrieved from the underlying data store. The indication "left" specifies that `hasManyRelationship` is declared on `TResource`.
HasManyAttribute	hasManyRelationship	The to-many relationship being set.
ISet<IIdentifiable>	rightResourceIds	The set of resource identifiers to replace any existing set with, coming from the request.
WriteOperationKind	writeOperation	Identifies the logical write operation for which this method was called. Possible values: CreateResource, UpdateResource and SetRelationship.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task

| Improve this Doc View Source

OnSetToOneRelationshipAsync(TResource, HasOneAttribute, IIdentifiable, WriteOperationKind, CancellationToken)

Executes before setting (or clearing) the resource at the right side of a to-one relationship.

Implementing this method enables to perform validations and change rightResourceId, before the relationship is updated.

Declaration

public virtual Task<IIdentifiable> OnSetToOneRelationshipAsync(TResource leftResource, HasOneAttribute hasOneRelationship, IIdentifiable rightResourceId, WriteOperationKind writeOperation, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	leftResource	The original resource as retrieved from the underlying data store. The indication "left" specifies that `hasOneRelationship` is declared on `TResource`.
HasOneAttribute	hasOneRelationship	The to-one relationship being set.
IIdentifiable	rightResourceId	The new resource identifier (or `null` to clear the relationship), coming from the request.
WriteOperationKind	writeOperation	Identifies the logical write operation for which this method was called. Possible values: CreateResource, UpdateResource and SetRelationship.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task<IIdentifiable>	The replacement resource identifier, or `null` to clear the relationship. Returns `rightResourceId` by default.

| Improve this Doc View Source

OnWriteSucceededAsync(TResource, WriteOperationKind, CancellationToken)

Executes after successfully writing the changed resource to the underlying data store, as part of a write request.

Implementing this method enables to run additional logic, for example enqueue a notification message on a service bus.

Declaration

public virtual Task OnWriteSucceededAsync(TResource resource, WriteOperationKind writeOperation, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	resource	The resource as written to the underlying data store.
WriteOperationKind	writeOperation	Identifies the logical write operation for which this method was called. Possible values: CreateResource, UpdateResource, DeleteResource, SetRelationship , AddToRelationship and RemoveFromRelationship.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task

| Improve this Doc View Source

OnWritingAsync(TResource, WriteOperationKind, CancellationToken)

Executes before writing the changed resource to the underlying data store, as part of a write request.

Implementing this method enables to perform validations and make changes to resource, after the fields from the request have been copied into it.

An example usage is to set the last-modification timestamp, overwriting the value from the incoming request.

Another use case is to add a notification message to an outbox table, which gets committed along with the resource write in a single transaction (see https://microservices.io/patterns/data/transactional-outbox.html).

Declaration

public virtual Task OnWritingAsync(TResource resource, WriteOperationKind writeOperation, CancellationToken cancellationToken)

Parameters

Type	Name	Description
TResource	resource	The original resource retrieved from the underlying data store (or a freshly instantiated resource in case of a POST resource request), updated with the changes from the incoming request. Exception: In case `writeOperation` is DeleteResource, AddToRelationship or RemoveFromRelationship, this is an empty object with only the Id property set, because for those endpoints no resource is retrieved upfront.
WriteOperationKind	writeOperation	Identifies the logical write operation for which this method was called. Possible values: CreateResource, UpdateResource, DeleteResource, SetRelationship , AddToRelationship and RemoveFromRelationship.
CancellationToken	cancellationToken	Propagates notification that request handling should be canceled.

Returns

Type	Description
Task

Implements

IResourceDefinition<TResource, TId>