Interface IElementEndpoint<TEntity>

Namespace

TypedRest.Endpoints.Generic

Assembly

TypedRest.dll

Endpoint for an individual resource.

public interface IElementEndpoint<TEntity> : IElementEndpoint, IEndpoint where TEntity : class

Type Parameters

TEntity

The type of entity the endpoint represents.

Inherited Members

IElementEndpoint.ExistsAsync(CancellationToken)

IElementEndpoint.DeleteAllowed

IElementEndpoint.DeleteAsync(CancellationToken)

IEndpoint.Uri

IEndpoint.HttpClient

IEndpoint.Serializers

IEndpoint.ErrorHandler

IEndpoint.LinkExtractor

IEndpoint.GetLinks(string)

IEndpoint.Link(string)

IEndpoint.LinkTemplate(string, IDictionary<string, object>)

IEndpoint.LinkTemplate(string, object)

Properties

MergeAllowed

Shows whether the server has indicated that MergeAsync(TEntity, CancellationToken) is currently allowed.

bool? MergeAllowed { get; }

Property Value

bool?

true if the method is allowed, false if the method is not allowed, null If no request has been sent yet or the server did not specify allowed methods.

Remarks

Uses cached data from last response.

Response

A cached copy of the entity as received from the server.

TEntity? Response { get; }

Property Value

TEntity

SetAllowed

Shows whether the server has indicated that SetAsync(TEntity, CancellationToken) is currently allowed.

bool? SetAllowed { get; }

Property Value

bool?

true if the method is allowed, false if the method is not allowed, null If no request has been sent yet or the server did not specify allowed methods.

Remarks

Uses cached data from last response.

Methods

MergeAsync(TEntity, CancellationToken)

Modifies an existing entity by merging changes on the server-side.

Task<TEntity?> MergeAsync(TEntity entity, CancellationToken cancellationToken = default)

Parameters

entity TEntity

The entity data to merge with the existing one.

cancellationToken CancellationToken

Used to cancel the request.

Returns

Task<TEntity>

The modified entity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.

Exceptions

InvalidOperationException

The entity has changed since it was last retrieved with ReadAsync(CancellationToken). Your changes were rejected to prevent a lost update.

InvalidDataException

BadRequest

AuthenticationException

Unauthorized

UnauthorizedAccessException

Forbidden

KeyNotFoundException

NotFound or Gone

HttpRequestException

Other non-success status code.

ReadAsync(CancellationToken)

Returns the entitiy.

Task<TEntity> ReadAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Used to cancel the request.

Returns

Task<TEntity>

Exceptions

AuthenticationException

Unauthorized

UnauthorizedAccessException

Forbidden

KeyNotFoundException

NotFound or Gone

HttpRequestException

Other non-success status code.

SetAsync(TEntity, CancellationToken)

Sets/replaces the entity.

Task<TEntity?> SetAsync(TEntity entity, CancellationToken cancellationToken = default)

Parameters

entity TEntity

The new entities.

cancellationToken CancellationToken

Used to cancel the request.

Returns

Task<TEntity>

The entity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.

Exceptions

InvalidOperationException

The entity has changed since it was last retrieved with ReadAsync(CancellationToken). Your changes were rejected to prevent a lost update.

InvalidDataException

BadRequest

AuthenticationException

Unauthorized

UnauthorizedAccessException

Forbidden

KeyNotFoundException

NotFound or Gone

HttpRequestException

Other non-success status code.

UpdateAsync(Action<JsonPatchDocument<TEntity>>, int, CancellationToken)

Applies a JSON Patch to the entity. Sends the patch instructions to the server for processing; falls back to local processing with optimistic concurrency if that fails.

Task<TEntity?> UpdateAsync(Action<JsonPatchDocument<TEntity>> patchAction, int maxRetries = 3, CancellationToken cancellationToken = default)

Parameters

patchAction Action<JsonPatchDocument<TEntity>>

Callback for building a patch document describing the desired modifications.

maxRetries int

The maximum number of retries to perform for optimistic concurrency before giving up.

cancellationToken CancellationToken

Used to cancel the request.

Returns

Task<TEntity>

The entity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.

Exceptions

InvalidOperationException

The number of retries performed for optimistic concurrency exceeded maxRetries.

NotSupportedException

Serializers does not contain a JsonMediaTypeFormatter.

InvalidDataException

BadRequest

AuthenticationException

Unauthorized

UnauthorizedAccessException

Forbidden

KeyNotFoundException

NotFound or Gone

HttpRequestException

Other non-success status code.

UpdateAsync(Action<TEntity>, int, CancellationToken)

Reads the current state of the entity, applies a change to it and stores the result. Applies optimistic concurrency using automatic retries.

Task<TEntity?> UpdateAsync(Action<TEntity> updateAction, int maxRetries = 3, CancellationToken cancellationToken = default)

Parameters

updateAction Action<TEntity>

A callback that takes the current state of the entity and applies the desired modifications.

maxRetries int

The maximum number of retries to perform for optimistic concurrency before giving up.

cancellationToken CancellationToken

Used to cancel the request.

Returns

Task<TEntity>

The entity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.

Exceptions

InvalidOperationException

The number of retries performed for optimistic concurrency exceeded maxRetries.

InvalidDataException

BadRequest

AuthenticationException

Unauthorized

UnauthorizedAccessException

Forbidden

KeyNotFoundException

NotFound or Gone

HttpRequestException

Other non-success status code.