Class ApiRequest<T1, T2, T3, T4, T5, T6, T7, T8>

Encapsulates information for building and making a request to a RESTful HTTP API. A response to this request may lead to a response content of one of the generic type parameters.

Inheritance

Object

HttpRequestMessageBuilder

ApiRequestBase

ApiRequest<T1, T2, T3, T4, T5, T6, T7, T8>

Implements

IHttpRequestMessageBuilder

IHttpHeadersBuilder<HttpRequestHeaders>

IHttpHeadersBuilder

IHttpRequestPropertiesBuilder

IHttpContentBuilder

IHttpProtocolVersionBuilder

IRequestUriBuilder

IHttpMethodBuilder

IBuilder

Namespace: ReqRest

Assembly: ReqRest.dll

Syntax

public sealed class ApiRequest<T1, T2, T3, T4, T5, T6, T7, T8> : ApiRequestBase, IHttpRequestMessageBuilder, IHttpHeadersBuilder<HttpRequestHeaders>, IHttpHeadersBuilder, IHttpRequestPropertiesBuilder, IHttpContentBuilder, IHttpProtocolVersionBuilder, IRequestUriBuilder, IHttpMethodBuilder, IBuilder

Type Parameters

Name	Description
T1	A type which may be returned by a response following this request.
T2	A type which may be returned by the response following this request.
T3	A type which may be returned by the response following this request.
T4	A type which may be returned by the response following this request.
T5	A type which may be returned by the response following this request.
T6	A type which may be returned by the response following this request.
T7	A type which may be returned by the response following this request.
T8	A type which may be returned by the response following this request.

Methods

FetchAsync(HttpCompletionOption, CancellationToken)

Sends the request, deserializes the HTTP content of the resulting HTTP response and returns both the response and the deserialized resource.

Declaration

public Task<(ApiResponse<T1, T2, T3, T4, T5, T6, T7, T8> Response, Variant<T1, T2, T3, T4, T5, T6, T7, T8> Resource)> FetchAsync(HttpCompletionOption completionOption = HttpCompletionOption.ResponseContentRead, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
HttpCompletionOption	completionOption	Defines when the operation should complete (as soon as a response is available or after reading the whole response content).
CancellationToken	cancellationToken	A cancellation token which can be used to cancel the operation.

Returns

Type	Description
Task<ValueTuple<ApiResponse<T1, T2, T3, T4, T5, T6, T7, T8>, NCommons.Monads.Variant<T1, T2, T3, T4, T5, T6, T7, T8>>>	A tuple which stores the response to the request and the resource which was deserialized from the response's HTTP content. The resource is represented through a NCommons.Monads.Variant`8 which holds a value that matches the response type declared for the response's HTTP status code. This variant is empty if the response's HTTP status code doesn't match any declared one.

Remarks

This method is designed for developer convenience and simply combines calling FetchResponseAsync(HttpCompletionOption, CancellationToken) and deserializing the resource afterwards.

Be aware that this method may throw an HttpContentSerializationException, because it runs the code of an arbitrary IHttpContentDeserializer.

This method uses the HttpClientProvider function for retrieving an HttpClient with which the request will be sent.

See the example for how to ideally use this method.

Examples

var (response, resource) = await request.FetchAsync();

// Note: The above is equivalent to calling these two lines manually:
var response = await request.FetchResponseAsync();
var resource = await response.DeserializeResourceAsync();

Console.WriteLine($"Received status {response.StatusCode}");
Console.WriteLine($"Received a resource of type {resource.Value?.GetType()}");

Exceptions

Type	Condition
TaskCanceledException	The operation was canceled via the `cancellationToken`.
HttpContentSerializationException	There was a resource to deserialize, but the underlying IHttpContentDeserializer threw an exception while deserializing the resource.
InvalidOperationException	The HttpClientProvider returned null.

Declaration

public Task<Variant<T1, T2, T3, T4, T5, T6, T7, T8>> FetchResourceAsync(HttpCompletionOption completionOption = HttpCompletionOption.ResponseContentRead, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
HttpCompletionOption	completionOption	Defines when the operation should complete (as soon as a response is available or after reading the whole response content).
CancellationToken	cancellationToken	A cancellation token which can be used to cancel the operation.

Returns

Type	Description
Task<NCommons.Monads.Variant<T1, T2, T3, T4, T5, T6, T7, T8>>	The deserialized resource represented through a NCommons.Monads.Variant`8 which holds a value that matches the response type declared for the response's HTTP status code. This variant is empty if the response's HTTP status code doesn't match any declared one.

Remarks

This method only returns the deserialized resource. Any other information about the HTTP response, for example the returned HTTP status code, is lost. If you are interested in any kind of information about the HTTP response, consider using the FetchAsync(HttpCompletionOption, CancellationToken) method.

Be aware that this method may throw an HttpContentSerializationException, because it runs the code of an arbitrary IHttpContentDeserializer.

This method uses the HttpClientProvider function for retrieving an HttpClient with which the request will be sent.

Examples

var resource = await response.FetchResourceAsync();
Console.WriteLine($"Received a resource of type {resource.Value?.GetType()}");

Exceptions

Type	Condition
TaskCanceledException	The operation was canceled via the `cancellationToken`.
HttpContentSerializationException	There was a resource to deserialize, but the underlying IHttpContentDeserializer threw an exception while deserializing the resource.
InvalidOperationException	The HttpClientProvider returned null.

Declaration

public Task<ApiResponse<T1, T2, T3, T4, T5, T6, T7, T8>> FetchResponseAsync(HttpCompletionOption completionOption = HttpCompletionOption.ResponseContentRead, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
HttpCompletionOption	completionOption	Defines when the operation should complete (as soon as a response is available or after reading the whole response content).
CancellationToken	cancellationToken	A cancellation token which can be used to cancel the operation.

Returns

Type	Description
Task<ApiResponse<T1, T2, T3, T4, T5, T6, T7, T8>>	The response to the request.

Remarks

This method only returns the HTTP response itself and does not perform any deserialization logic. To access the underlying resource, use the DeserializeResourceAsync() method of the response.

Consider using the FetchAsync(HttpCompletionOption, CancellationToken) method if you are interested in both the response and the underlying resource.

This method uses the HttpClientProvider function for retrieving an HttpClient with which the request will be sent.

Examples

var response = await request.FetchResponseAsync();
var resource = await response.DeserializeResourceAsync();

Console.WriteLine($"Received status {response.StatusCode}");
Console.WriteLine($"Received a resource of type {resource.Value?.GetType()}");