Table of Contents

Class JsonApiOptions

Namespace
JsonApiDotNetCore.Configuration
Assembly
JsonApiDotNetCore.dll

Global options that configure the behavior of JsonApiDotNetCore.

[PublicAPI]
public sealed class JsonApiOptions : IJsonApiOptions
Inheritance
JsonApiOptions
Implements
Inherited Members

Constructors

JsonApiOptions() 

public JsonApiOptions()

Properties

AllowClientGeneratedIds

Whether clients can provide IDs when creating resources. When not allowed, a 403 Forbidden response is returned if a client attempts to create a resource with a defined ID. false by default.

[Obsolete("Use ClientIdGeneration instead.")]
public bool AllowClientGeneratedIds { get; set; }

Property Value

bool

Remarks

Setting this to true corresponds to Allowed, while false corresponds to Forbidden.

AllowUnknownFieldsInRequestBody

Whether to produce an error on unknown attribute and relationship keys in request bodies. false by default.

public bool AllowUnknownFieldsInRequestBody { get; set; }

Property Value

bool

AllowUnknownQueryStringParameters

Whether to produce an error on unknown query string parameters. false by default.

public bool AllowUnknownQueryStringParameters { get; set; }

Property Value

bool

ClientIdGeneration

Whether clients are allowed or required to provide IDs when creating resources. Forbidden by default. This setting can be overruled per resource type using ClientIdGeneration.

public ClientIdGenerationMode ClientIdGeneration { get; set; }

Property Value

ClientIdGenerationMode

DefaultAttrCapabilities

Specifies the default set of allowed capabilities on JSON:API attributes. Defaults to All. This setting can be overruled per attribute using Capabilities.

public AttrCapabilities DefaultAttrCapabilities { get; set; }

Property Value

AttrCapabilities

DefaultHasManyCapabilities

Specifies the default set of allowed capabilities on JSON:API to-many relationships. Defaults to All. This setting can be overruled per relationship using Capabilities.

public HasManyCapabilities DefaultHasManyCapabilities { get; set; }

Property Value

HasManyCapabilities

DefaultHasOneCapabilities

Specifies the default set of allowed capabilities on JSON:API to-one relationships. Defaults to All. This setting can be overruled per relationship using Capabilities.

public HasOneCapabilities DefaultHasOneCapabilities { get; set; }

Property Value

HasOneCapabilities

DefaultPageSize

The page size (10 by default) that is used when not specified in query string. Set to null to not use pagination by default.

public PageSize? DefaultPageSize { get; set; }

Property Value

PageSize

EnableLegacyFilterNotation

Determines whether legacy filter notation in query strings (such as =eq:, =like:, and =in:) is enabled. false by default.

public bool EnableLegacyFilterNotation { get; set; }

Property Value

bool

Extensions

Lists the JSON:API extensions that are turned on. Empty by default, but if your project contains a controller that derives from BaseJsonApiOperationsController, the AtomicOperations and RelaxedAtomicOperations extensions are automatically added.

public IReadOnlySet<JsonApiMediaTypeExtension> Extensions { get; set; }

Property Value

IReadOnlySet<JsonApiMediaTypeExtension>

Remarks

To implement a custom JSON:API extension, add it here and override GetPossibleMediaTypes() to indicate which combinations of extensions are available, depending on the current endpoint. Use Extensions to obtain the active extensions when implementing extension-specific logic.

IncludeExceptionStackTraceInErrors

Whether to include Exception stack traces in Meta responses. false by default.

public bool IncludeExceptionStackTraceInErrors { get; set; }

Property Value

bool

IncludeJsonApiVersion

Whether to include a 'jsonapi' object in responses, which contains the highest JSON:API version supported. false by default.

public bool IncludeJsonApiVersion { get; set; }

Property Value

bool

IncludeRequestBodyInErrors

Whether to include the request body in Meta responses when it is invalid. false by default.

public bool IncludeRequestBodyInErrors { get; set; }

Property Value

bool

IncludeTotalResourceCount

Whether to include the total resource count in top-level meta objects. This requires an additional database query. false by default.

public bool IncludeTotalResourceCount { get; set; }

Property Value

bool

MaximumIncludeDepth

Controls how many levels deep includes are allowed to be nested. For example, MaximumIncludeDepth=1 would allow ?include=articles but not ?include=articles.revisions. null by default, which means unconstrained.

public int? MaximumIncludeDepth { get; set; }

Property Value

int?

MaximumOperationsPerRequest

Limits the maximum number of operations allowed per atomic:operations request. Defaults to 10. Set to null for unlimited.

public int? MaximumOperationsPerRequest { get; set; }

Property Value

int?

MaximumPageNumber

The maximum page number that can be used, or null for unconstrained (default).

public PageNumber? MaximumPageNumber { get; set; }

Property Value

PageNumber

MaximumPageSize

The maximum page size that can be used, or null for unconstrained (default).

public PageSize? MaximumPageSize { get; set; }

Property Value

PageSize

Namespace

The URL prefix to use for exposed endpoints.

public string? Namespace { get; set; }

Property Value

string

Examples

options.Namespace = "api/shopping";

Configures which links to write in the RelationshipLinks object. Defaults to All. This setting can be overruled for all relationships per resource type by adding ResourceLinksAttribute on the class definition of a resource. This can be further overruled per relationship by setting Links.

public LinkTypes RelationshipLinks { get; set; }

Property Value

LinkTypes

Configures which links to write in the ResourceLinks object. Defaults to All. This setting can be overruled per resource type by adding ResourceLinksAttribute on the class definition of a resource.

public LinkTypes ResourceLinks { get; set; }

Property Value

LinkTypes

SerializerOptions

Enables to customize the settings that are used by the JsonSerializer.

public JsonSerializerOptions SerializerOptions { get; }

Property Value

JsonSerializerOptions

Examples

The next example sets the naming convention to camel casing.

options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
options.SerializerOptions.DictionaryKeyPolicy = JsonNamingPolicy.CamelCase;

Configures which links to write in the TopLevelLinks object. Defaults to All. This setting can be overruled per resource type by adding ResourceLinksAttribute on the class definition of a resource.

public LinkTypes TopLevelLinks { get; set; }

Property Value

LinkTypes

TransactionIsolationLevel

Enables to override the default isolation level for database transactions, enabling to balance between consistency and performance. Defaults to null, which leaves this up to Entity Framework Core to choose (and then it varies per database provider).

public IsolationLevel? TransactionIsolationLevel { get; set; }

Property Value

IsolationLevel?

Whether to use relative links for all resources. false by default.

public bool UseRelativeLinks { get; set; }

Property Value

bool
options.UseRelativeLinks = true;
{
  "type": "articles",
  "id": "4309",
  "relationships": {
     "author": {
       "links": {
         "self": "/api/shopping/articles/4309/relationships/author",
         "related": "/api/shopping/articles/4309/author"
       }
     }
  }
}

ValidateModelState

Whether ASP.NET ModelState validation is enabled. true by default.

public bool ValidateModelState { get; set; }

Property Value

bool

Methods

IncludeExtensions(params JsonApiMediaTypeExtension[])

Adds the specified JSON:API extensions to the existing Extensions set.

public void IncludeExtensions(params JsonApiMediaTypeExtension[] extensionsToAdd)

Parameters

extensionsToAdd JsonApiMediaTypeExtension[]

The JSON:API extensions to add.

Edit this page