TypedRest for .NET 1.3.5
build type-safe fluent-style REST API clients
TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity > Interface Template Reference

Endpoint for an individual resource. More...

Inheritance diagram for TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >:
TypedRest.Endpoints.IEndpoint

Public Member Functions

Task< bool > ExistsAsync (CancellationToken cancellationToken=default)
 Determines whether the element currently exists. More...
 
Task DeleteAsync (CancellationToken cancellationToken=default)
 Deletes the element. More...
 
Task< TEntity > ReadAsync (CancellationToken cancellationToken=default)
 Returns the TEntity . More...
 
Task< TEntity?> SetAsync (TEntity entity, CancellationToken cancellationToken=default)
 Sets/replaces the TEntity . More...
 
Task< TEntity?> MergeAsync (TEntity entity, CancellationToken cancellationToken=default)
 Modifies an existing TEntity by merging changes on the server-side. More...
 
Task< TEntity?> UpdateAsync (Action< TEntity > updateAction, int maxRetries=3, CancellationToken cancellationToken=default)
 Reads the current state of the entity, applies a change to it and stores the result. Applies optimistic concurrency using automatic retries. More...
 
Task< TEntity?> UpdateAsync (Action< JsonPatchDocument< TEntity > > patchAction, int maxRetries=3, CancellationToken cancellationToken=default)
 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. More...
 
- Public Member Functions inherited from TypedRest.Endpoints.IEndpoint
IReadOnlyList<(Uri uri, string? title)> GetLinks (string rel)
 Resolves all links with a specific relation type. Uses cached data from last response. More...
 
Uri Link (string rel)
 Resolves a single link with a specific relation type. Uses cached data from last response if possible. Tries lazy lookup with HTTP HEAD on cache miss. More...
 
Uri LinkTemplate (string rel, IDictionary< string, object > variables)
 Resolves a link template with a specific relation type. Uses cached data from last response if possible. Tries lazy lookup with HTTP HEAD on cache miss. More...
 
Uri LinkTemplate (string rel, object variables)
 Resolves a link template with a specific relation type. More...
 

Properties

bool? DeleteAllowed [get]
 Shows whether the server has indicated that DeleteAsync is currently allowed. More...
 
TEntity? Response [get]
 A cached copy of the entity as received from the server.
 
bool? SetAllowed [get]
 Shows whether the server has indicated that SetAsync is currently allowed. More...
 
bool? MergeAllowed [get]
 Shows whether the server has indicated that MergeAsync is currently allowed. More...
 
- Properties inherited from TypedRest.Endpoints.IEndpoint
Uri Uri [get]
 The HTTP URI of the remote resource.
 
HttpClient HttpClient [get]
 The HTTP client used to communicate with the remote resource.
 
MediaTypeFormatter Serializer [get]
 Controls the serialization of entities sent to and received from the server.
 
IErrorHandler ErrorHandler [get]
 Handles errors in responses.
 
ILinkExtractor LinkExtractor [get]
 Extracts links from responses.
 

Detailed Description

Endpoint for an individual resource.

Template Parameters
TEntityThe type of entity the endpoint represents.
Type Constraints
TEntity :class 

Member Function Documentation

◆ DeleteAsync()

Task TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.DeleteAsync ( CancellationToken  cancellationToken = default)

Deletes the element.

Parameters
cancellationTokenUsed to cancel the request.
Exceptions
InvalidOperationExceptionThe entity has changed since it was last retrieved with IElementEndpoint<T>.ReadAsync. Your delete call was rejected to prevent a lost update.
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
KeyNotFoundExceptionHttpStatusCode.NotFound or HttpStatusCode.Gone
HttpRequestExceptionOther non-success status code.

◆ ExistsAsync()

Task< bool > TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.ExistsAsync ( CancellationToken  cancellationToken = default)

Determines whether the element currently exists.

Parameters
cancellationTokenUsed to cancel the request.
Exceptions
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
HttpRequestExceptionOther non-success status code.

◆ MergeAsync()

Task< TEntity?> TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.MergeAsync ( TEntity  entity,
CancellationToken  cancellationToken = default 
)

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

Parameters
entityThe TEntity data to merge with the existing one.
cancellationTokenUsed to cancel the request.
Returns
The modified TEntity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.
Exceptions
InvalidOperationExceptionThe entity has changed since it was last retrieved with ReadAsync. Your changes were rejected to prevent a lost update.
InvalidDataExceptionHttpStatusCode.BadRequest
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
KeyNotFoundExceptionHttpStatusCode.NotFound or HttpStatusCode.Gone
HttpRequestExceptionOther non-success status code.

◆ ReadAsync()

Task< TEntity > TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.ReadAsync ( CancellationToken  cancellationToken = default)

Returns the TEntity .

Parameters
cancellationTokenUsed to cancel the request.
Exceptions
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
KeyNotFoundExceptionHttpStatusCode.NotFound or HttpStatusCode.Gone
HttpRequestExceptionOther non-success status code.

◆ SetAsync()

Task< TEntity?> TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.SetAsync ( TEntity  entity,
CancellationToken  cancellationToken = default 
)

Sets/replaces the TEntity .

Parameters
entityThe new TEntity .
cancellationTokenUsed to cancel the request.
Returns
The TEntity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.
Exceptions
InvalidOperationExceptionThe entity has changed since it was last retrieved with ReadAsync. Your changes were rejected to prevent a lost update.
InvalidDataExceptionHttpStatusCode.BadRequest
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
KeyNotFoundExceptionHttpStatusCode.NotFound or HttpStatusCode.Gone
HttpRequestExceptionOther non-success status code.

◆ UpdateAsync() [1/2]

Task< TEntity?> TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.UpdateAsync ( Action< JsonPatchDocument< TEntity > >  patchAction,
int  maxRetries = 3,
CancellationToken  cancellationToken = default 
)

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.

Parameters
patchActionCallback for building a patch document describing the desired modifications.
maxRetriesThe maximum number of retries to perform for optimistic concurrency before giving up.
cancellationTokenUsed to cancel the request.
Returns
The TEntity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.
Exceptions
InvalidOperationExceptionThe number of retries performed for optimistic concurrency exceeded maxRetries .
NotSupportedExceptionIEndpoint.Serializer is not a JsonMediaTypeFormatter.
InvalidDataExceptionHttpStatusCode.BadRequest
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
KeyNotFoundExceptionHttpStatusCode.NotFound or HttpStatusCode.Gone
HttpRequestExceptionOther non-success status code.

◆ UpdateAsync() [2/2]

Task< TEntity?> TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.UpdateAsync ( Action< TEntity >  updateAction,
int  maxRetries = 3,
CancellationToken  cancellationToken = default 
)

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

Parameters
updateActionA callback that takes the current state of the entity and applies the desired modifications.
maxRetriesThe maximum number of retries to perform for optimistic concurrency before giving up.
cancellationTokenUsed to cancel the request.
Returns
The TEntity as returned by the server, possibly with additional fields set. null if the server does not respond with a result entity.
Exceptions
InvalidOperationExceptionThe number of retries performed for optimistic concurrency exceeded maxRetries .
InvalidDataExceptionHttpStatusCode.BadRequest
AuthenticationExceptionHttpStatusCode.Unauthorized
UnauthorizedAccessExceptionHttpStatusCode.Forbidden
KeyNotFoundExceptionHttpStatusCode.NotFound or HttpStatusCode.Gone
HttpRequestExceptionOther non-success status code.

Property Documentation

◆ DeleteAllowed

bool? TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.DeleteAllowed
get

Shows whether the server has indicated that DeleteAsync is currently allowed.

Uses cached data from last response.

Returns
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.

◆ MergeAllowed

bool? TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.MergeAllowed
get

Shows whether the server has indicated that MergeAsync is currently allowed.

Uses cached data from last response.

Returns
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.

◆ SetAllowed

bool? TypedRest.Endpoints.Generic.IElementEndpoint< out out TEntity >.SetAllowed
get

Shows whether the server has indicated that SetAsync is currently allowed.

Uses cached data from last response.

Returns
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.

The documentation for this interface was generated from the following file: