Class EndpointBase

Namespace

TypedRest.Endpoints

Assembly

TypedRest.dll

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

public abstract class EndpointBase : IEndpoint

Inheritance

object

EndpointBase

Implements

IEndpoint

Derived

EntryEndpoint

CachingEndpointBase

IndexerEndpoint<TElementEndpoint>

BlobEndpoint

UploadEndpoint

StreamingEndpoint<TEntity>

RpcEndpointBase

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Constructors

EndpointBase(Uri, HttpClient, IReadOnlyList<MediaTypeFormatter>, IErrorHandler, ILinkExtractor)

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

protected EndpointBase(Uri uri, HttpClient httpClient, IReadOnlyList<MediaTypeFormatter> serializers, IErrorHandler errorHandler, ILinkExtractor linkExtractor)

Parameters

uri Uri

The HTTP URI of the remote element.

httpClient HttpClient

The HTTP client used to communicate with the remote element.

serializers IReadOnlyList<MediaTypeFormatter>

A list of serializers used for entities received from the server, sorted from most to least preferred. Always uses first for sending to the server.

errorHandler IErrorHandler

Handles errors in HTTP responses.

linkExtractor ILinkExtractor

Detects links in HTTP responses.

EndpointBase(IEndpoint, string)

Creates a new endpoint with a relative URI.

protected EndpointBase(IEndpoint referrer, string relativeUri)

Parameters

referrer IEndpoint

The endpoint used to navigate to this one.

relativeUri string

The URI of this endpoint relative to the referrer's. Add a ./ prefix here to imply a trailing slash referrer's URI.

EndpointBase(IEndpoint, Uri)

Creates a new endpoint with a relative URI.

protected EndpointBase(IEndpoint referrer, Uri relativeUri)

Parameters

referrer IEndpoint

The endpoint used to navigate to this one.

relativeUri Uri

The URI of this endpoint relative to the referrer's.

Properties

ErrorHandler

Handles errors in responses.

public IErrorHandler ErrorHandler { get; }

Property Value

IErrorHandler

HttpClient

The HTTP client used to communicate with the remote resource.

public HttpClient HttpClient { get; }

Property Value

HttpClient

LinkExtractor

Extracts links from responses.

public ILinkExtractor LinkExtractor { get; }

Property Value

ILinkExtractor

Serializer

The serializer used for entities sent to the server. Equal to the first entry in Serializers.

protected virtual MediaTypeFormatter Serializer { get; }

Property Value

MediaTypeFormatter

Exceptions

InvalidOperationException

Serializers is empty.

Serializers

A list of serializers used for entities received from the server, sorted from most to least preferred. Always uses first for sending to the server.

public IReadOnlyList<MediaTypeFormatter> Serializers { get; }

Property Value

IReadOnlyList<MediaTypeFormatter>

Uri

The HTTP URI of the remote resource.

public Uri Uri { get; }

Property Value

Uri

Methods

FinalizeAsync(Func<Task<HttpResponseMessage>>, string)

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

protected Task FinalizeAsync(Func<Task<HttpResponseMessage>> request, string caller = "unknown")

Parameters

request Func<Task<HttpResponseMessage>>

A callback that performs the actual HTTP request.

caller string

The name of the method calling this method.

Returns

Task

GetConstructor<TEndpoint>()

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

protected static Func<IEndpoint, Uri, TEndpoint> GetConstructor<TEndpoint>() where TEndpoint : IEndpoint

Returns

Func<IEndpoint, Uri, TEndpoint>

Type Parameters

TEndpoint

Exceptions

ArgumentException

No suitable constructor found on TEndpoint.

GetLinkTemplate(string)

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

public UriTemplate GetLinkTemplate(string rel)

Parameters

rel string

The relation type of the link template to look for.

Returns

UriTemplate

The unresolved link template.

Remarks

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

Exceptions

KeyNotFoundException

No link template with the specified rel could be found.

GetLinks(string)

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

public IReadOnlyList<(Uri uri, string? title)> GetLinks(string rel)

Parameters

rel string

The relation type of the links to look for.

Returns

IReadOnlyList<(Uri uri, string title)>

HandleAsync(Func<Task<HttpResponseMessage>>, string)

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

protected virtual Task<HttpResponseMessage> HandleAsync(Func<Task<HttpResponseMessage>> request, string caller = "unknown")

Parameters

request Func<Task<HttpResponseMessage>>

A callback that performs the actual HTTP request.

caller string

The name of the method calling this method.

Returns

Task<HttpResponseMessage>

The resolved request.

HandleCapabilities(HttpResponseMessage)

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

protected virtual void HandleCapabilities(HttpResponseMessage response)

Parameters

response HttpResponseMessage

IsMethodAllowed(HttpMethod)

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

protected bool? IsMethodAllowed(HttpMethod method)

Parameters

method HttpMethod

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

Returns

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.

Link(string)

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.

public Uri Link(string rel)

Parameters

rel string

The relation type of the link to look for.

Returns

Uri

Exceptions

KeyNotFoundException

No link with the specified rel could be found.

LinkTemplate(string, IDictionary<string, object>)

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.

public Uri LinkTemplate(string rel, IDictionary<string, object> variables)

Parameters

rel string

The relation type of the link template to look for.

variables IDictionary<string, object>

Variables for resolving the template.

Returns

Uri

The href of the link resolved relative to this endpoint's URI.

Exceptions

KeyNotFoundException

No link template with the specified rel could be found.

LinkTemplate(string, object)

Resolves a link template with a specific relation type.

public Uri LinkTemplate(string rel, object variables)

Parameters

rel string

The relation type of the link template to look for.

variables object

An object used to provide properties for resolving the template.

Returns

Uri

The href of the link resolved relative to this endpoint's URI.

Remarks

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

Exceptions

KeyNotFoundException

No link template with the specified rel could be found.

SetDefaultLink(string, string?)

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.

public void SetDefaultLink(string rel, string? href)

Parameters

rel string

The relation type of the link to add.

href string

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

Remarks

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

See Also

GetLinks(string)

Link(string)

SetDefaultLinkTemplate(string, string?)

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.

public void SetDefaultLinkTemplate(string rel, string? href)

Parameters

rel string

The relation type of the link template to add.

href string

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

Remarks

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

See Also

LinkTemplate(string, object)

StartActivity(string)

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

protected Activity? StartActivity(string caller = "unknown")

Parameters

caller string

The name of the method calling this method.

Returns

Activity

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.