TypedRest for .NET 1.3.5
build type-safe fluent-style REST API clients
TypedRest.Endpoints.EndpointBase Class Reference

Base class for building endpoints, i.e. remote HTTP resources. More...

Inheritance diagram for TypedRest.Endpoints.EndpointBase:
TypedRest.Endpoints.IEndpoint TypedRest.Endpoints.EntryEndpoint TypedRest.Endpoints.Generic.CachingEndpointBase TypedRest.Endpoints.Generic.IndexerEndpoint< TElementEndpoint > TypedRest.Endpoints.Raw.BlobEndpoint TypedRest.Endpoints.Raw.UploadEndpoint TypedRest.Endpoints.Reactive.StreamingEndpoint< TEntity > TypedRest.Endpoints.Rpc.RpcEndpointBase TypedRest.Endpoints.Generic.CollectionEndpoint< TEntity, TElementEndpoint > TypedRest.Endpoints.Generic.ElementEndpoint< TEntity > TypedRest.Endpoints.Rpc.ActionEndpoint TypedRest.Endpoints.Rpc.ConsumerEndpoint< TEntity > TypedRest.Endpoints.Rpc.FunctionEndpoint< TEntity, TResult > TypedRest.Endpoints.Rpc.ProducerEndpoint< TResult > TypedRest.Endpoints.Reactive.StreamingCollectionEndpoint< TEntity, TElementEndpoint > TypedRest.Endpoints.Reactive.PollingEndpoint< TEntity >

Public Member Functions

void SetDefaultLink (string rel, string? href)
 Registers one or more default links for a specific relation type. These links are used when no links with this relation type are provided by the server. This should only be called during initial setup of the endpoint. More...
 
void SetDefaultLinkTemplate (string rel, string? href)
 Registers a default link template for a specific relation type. This template is used when no template with this relation type is provided by the server. This should only be called during initial setup of the endpoint. More...
 
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...
 
UriTemplate GetLinkTemplate (string rel)
 Retrieves a link template with a specific relation type. Prefer IEndpoint.LinkTemplate(string,object) when possible. 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...
 
override string ToString ()
 

Protected Member Functions

 EndpointBase (Uri uri, HttpClient httpClient, MediaTypeFormatter serializer, IErrorHandler errorHandler, ILinkExtractor linkExtractor)
 Creates a new endpoint with an absolute URI. More...
 
 EndpointBase (IEndpoint referrer, Uri relativeUri)
 Creates a new endpoint with a relative URI. More...
 
 EndpointBase (IEndpoint referrer, string relativeUri)
 Creates a new endpoint with a relative URI. More...
 
virtual async Task< HttpResponseMessage > HandleAsync (Func< Task< HttpResponseMessage > > request, [CallerMemberName] string caller="unknown")
 Handles various cross-cutting concerns regarding a response message such as discovering links and handling errors. More...
 
Activity? StartActivity ([CallerMemberName] string caller="unknown")
 Starts a new Activity if there is any listener registered (e.g. OpenTelemetry), returns null otherwise. More...
 
virtual void HandleCapabilities (HttpResponseMessage response)
 Handles allowed HTTP methods and other capabilities reported by the server. More...
 
bool? IsMethodAllowed (HttpMethod method)
 Shows whether the server has indicated that a specific HTTP method is currently allowed. More...
 

Static Protected Member Functions

static Func< IEndpoint, Uri, TEndpoint > GetConstructor< TEndpoint > ()
 Returns a constructor for TEndpoint as a function with a referrer an a relative URI as input. More...
 

Properties

Uri Uri [get]
 
HttpClient HttpClient [get]
 
MediaTypeFormatter Serializer [get]
 
IErrorHandler ErrorHandler [get]
 
ILinkExtractor LinkExtractor [get]
 
- 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

Base class for building endpoints, i.e. remote HTTP resources.

Constructor & Destructor Documentation

◆ EndpointBase() [1/3]

TypedRest.Endpoints.EndpointBase.EndpointBase ( Uri  uri,
HttpClient  httpClient,
MediaTypeFormatter  serializer,
IErrorHandler  errorHandler,
ILinkExtractor  linkExtractor 
)
inlineprotected

Creates a new endpoint with an absolute URI.

Parameters
uriThe HTTP URI of the remote element.
httpClientThe HTTP client used to communicate with the remote element.
serializerControls the serialization of entities sent to and received from the server.
errorHandlerHandles errors in HTTP responses.
linkExtractorDetects links in HTTP responses.

◆ EndpointBase() [2/3]

TypedRest.Endpoints.EndpointBase.EndpointBase ( IEndpoint  referrer,
Uri  relativeUri 
)
inlineprotected

Creates a new endpoint with a relative URI.

Parameters
referrerThe endpoint used to navigate to this one.
relativeUriThe URI of this endpoint relative to the referrer 's.

◆ EndpointBase() [3/3]

TypedRest.Endpoints.EndpointBase.EndpointBase ( IEndpoint  referrer,
string  relativeUri 
)
inlineprotected

Creates a new endpoint with a relative URI.

Parameters
referrerThe endpoint used to navigate to this one.
relativeUriThe URI of this endpoint relative to the referrer 's. Add a ./ prefix here to imply a trailing slash referrer 's URI.

Member Function Documentation

◆ GetConstructor< TEndpoint >()

static Func< IEndpoint, Uri, TEndpoint > TypedRest.Endpoints.EndpointBase.GetConstructor< TEndpoint > ( )
inlinestaticprotected

Returns a constructor for TEndpoint as a function with a referrer an a relative URI as input.

Exceptions
ArgumentExceptionNo suitable constructor found on TEndpoint .
Type Constraints
TEndpoint :IEndpoint 

◆ GetLinks()

IReadOnlyList<(Uri uri, string? title)> TypedRest.Endpoints.EndpointBase.GetLinks ( string  rel)
inline

Resolves all links with a specific relation type. Uses cached data from last response.

Parameters
relThe relation type of the links to look for.

Implements TypedRest.Endpoints.IEndpoint.

◆ GetLinkTemplate()

UriTemplate TypedRest.Endpoints.EndpointBase.GetLinkTemplate ( string  rel)
inline

Retrieves a link template with a specific relation type. Prefer IEndpoint.LinkTemplate(string,object) when possible.

Parameters
relThe relation type of the link template to look for.
Returns
The unresolved link template.
Exceptions
KeyNotFoundExceptionNo link template with the specified rel could be found.

Uses cached data from last response if possible. Tries lazy lookup with HTTP HEAD on cache miss.

◆ HandleAsync()

virtual async Task< HttpResponseMessage > TypedRest.Endpoints.EndpointBase.HandleAsync ( Func< Task< HttpResponseMessage > >  request,
[CallerMemberName] string  caller = "unknown" 
)
inlineprotectedvirtual

Handles various cross-cutting concerns regarding a response message such as discovering links and handling errors.

Parameters
requestA callback that performs the actual HTTP request.
callerThe name of the method calling this method.
Returns
The resolved request .

Reimplemented in TypedRest.Endpoints.Reactive.PollingEndpoint< TEntity >.

◆ HandleCapabilities()

virtual void TypedRest.Endpoints.EndpointBase.HandleCapabilities ( HttpResponseMessage  response)
inlineprotectedvirtual

Handles allowed HTTP methods and other capabilities reported by the server.

Reimplemented in TypedRest.Endpoints.Generic.CollectionEndpoint< TEntity, TElementEndpoint >.

◆ IsMethodAllowed()

bool? TypedRest.Endpoints.EndpointBase.IsMethodAllowed ( HttpMethod  method)
inlineprotected

Shows whether the server has indicated that a specific HTTP method is currently allowed.

Parameters
methodThe HTTP methods (e.g. GET, POST, ...) to check.

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.

◆ Link()

Uri TypedRest.Endpoints.EndpointBase.Link ( string  rel)
inline

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.

Parameters
relThe relation type of the link to look for.
Exceptions
KeyNotFoundExceptionNo link with the specified rel could be found.

Implements TypedRest.Endpoints.IEndpoint.

◆ LinkTemplate() [1/2]

Uri TypedRest.Endpoints.EndpointBase.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.

Parameters
relThe relation type of the link template to look for.
variablesVariables for resolving the template.
Returns
The href of the link resolved relative to this endpoint's URI.
Exceptions
KeyNotFoundExceptionNo link template with the specified rel could be found.

Implements TypedRest.Endpoints.IEndpoint.

◆ LinkTemplate() [2/2]

Uri TypedRest.Endpoints.EndpointBase.LinkTemplate ( string  rel,
object  variables 
)

Resolves a link template with a specific relation type.

Parameters
relThe relation type of the link template to look for.
variablesAn object used to provide properties for resolving the template.
Returns
The href of the link resolved relative to this endpoint's URI.
Exceptions
KeyNotFoundExceptionNo link template with the specified rel could be found.

Uses cached data from last response if possible. Tries lazy lookup with HTTP HEAD on cache miss.

Implements TypedRest.Endpoints.IEndpoint.

◆ SetDefaultLink()

void TypedRest.Endpoints.EndpointBase.SetDefaultLink ( string  rel,
string?  href 
)
inline

Registers one or more default links for a specific relation type. These links are used when no links with this relation type are provided by the server. This should only be called during initial setup of the endpoint.

Parameters
relThe relation type of the link to add.
hrefThe href of the link relative to this endpoint's URI. Use null to remove any previous entries for the relation type.

This method is not thread-safe! Call this before performing any requests.

See also
IEndpoint.GetLinks, IEndpoint.Link

◆ SetDefaultLinkTemplate()

void TypedRest.Endpoints.EndpointBase.SetDefaultLinkTemplate ( string  rel,
string?  href 
)
inline

Registers a default link template for a specific relation type. This template is used when no template with this relation type is provided by the server. This should only be called during initial setup of the endpoint.

Parameters
relThe relation type of the link template to add.
hrefThe href of the link template relative to this endpoint's URI. Use null to remove any previous entry for the relation type.

This method is not thread-safe! Call this before performing any requests.

See also
IEndpoint.LinkTemplate(string,object)

◆ StartActivity()

Activity? TypedRest.Endpoints.EndpointBase.StartActivity ( [CallerMemberName] string  caller = "unknown")
protected

Starts a new Activity if there is any listener registered (e.g. OpenTelemetry), returns null otherwise.

Parameters
callerThe name of the method calling this method.

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