Class ApiRequest<T1, T2, T3>

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>
Namespace: ReqRest
Assembly: ReqRest.dll
Syntax
public sealed class ApiRequest<T1, T2, T3> : 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.

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> Response, Variant<T1, T2, T3> 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>, NCommons.Monads.Variant<T1, T2, T3>>>

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`3 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.
See Also

FetchResourceAsync(HttpCompletionOption, CancellationToken)

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

Declaration
public Task<Variant<T1, T2, T3>> 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>>

The deserialized resource represented through a NCommons.Monads.Variant`3 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.
See Also

FetchResponseAsync(HttpCompletionOption, CancellationToken)

Sends the request and returns the resulting HTTP response without serializing its HTTP content.

Declaration
public Task<ApiResponse<T1, T2, T3>> 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>>

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()}");
Exceptions
Type Condition
TaskCanceledException

The operation was canceled via the cancellationToken.
InvalidOperationException

The HttpClientProvider returned null.
See Also

Receive<T4>()

Declares that the response to this request may have a content of type T4. This returns a builder instance which requires you to specify additional information about the possible response (for example, for which status codes the type is a possible result).

Declaration
public ResponseTypeInfoBuilder<ApiRequest<T1, T2, T3, T4>> Receive<T4>()
Returns
Type Description
ResponseTypeInfoBuilder<ApiRequest<T1, T2, T3, T4>>

An ResponseTypeInfoBuilder<TRequest> instance which must be used to specify additional information about the possible response.
Type Parameters
Name Description
T4

The .NET type which may be returned by the response following this request.

ReceiveByteArray(StatusCodeRange[])

Declaration
public ApiRequest<T1, T2, T3, byte[]> ReceiveByteArray(params StatusCodeRange[] forStatusCodes)
Parameters
Type Name Description
StatusCodeRange[] forStatusCodes
Returns
Type Description
ApiRequest<T1, T2, T3, Byte[]>

ReceiveByteArray(IEnumerable<StatusCodeRange>)

Declares that the response to this request may have an HTTP content which can be read as a Byte array.

Declaration
public ApiRequest<T1, T2, T3, byte[]> ReceiveByteArray(IEnumerable<StatusCodeRange> forStatusCodes)
Parameters
Type Name Description
IEnumerable<StatusCodeRange> forStatusCodes

A set of status codes for which the HTTP content may be read as a Byte array.
Returns
Type Description
ApiRequest<T1, T2, T3, Byte[]>

An ApiRequestBase, upgraded with the Byte array type.
Exceptions
Type Condition
ArgumentNullException
  • forStatusCodes
ArgumentException

forStatusCodes is empty.

ReceiveNoContent()

Declares that the response to this request may have an empty HTTP content when receiving a response with status code 204 No Content.

Declaration
public ApiRequest<T1, T2, T3, NoContent> ReceiveNoContent()
Returns
Type Description
ApiRequest<T1, T2, T3, NoContent>

An ApiRequestBase, upgraded with the NoContent type.

ReceiveNoContent(StatusCodeRange[])

Declaration
public ApiRequest<T1, T2, T3, NoContent> ReceiveNoContent(params StatusCodeRange[] forStatusCodes)
Parameters
Type Name Description
StatusCodeRange[] forStatusCodes
Returns
Type Description
ApiRequest<T1, T2, T3, NoContent>

ReceiveNoContent(IEnumerable<StatusCodeRange>)

Declares that the response to this request may have an empty HTTP content, represented through the NoContent type.

Declaration
public ApiRequest<T1, T2, T3, NoContent> ReceiveNoContent(IEnumerable<StatusCodeRange> forStatusCodes)
Parameters
Type Name Description
IEnumerable<StatusCodeRange> forStatusCodes

A set of status codes for which no content is received.
Returns
Type Description
ApiRequest<T1, T2, T3, NoContent>

An ApiRequestBase, upgraded with the NoContent type.
Exceptions
Type Condition
ArgumentNullException
  • forStatusCodes
ArgumentException

forStatusCodes is empty.

ReceiveString(StatusCodeRange[])

Declaration
public ApiRequest<T1, T2, T3, string> ReceiveString(params StatusCodeRange[] forStatusCodes)
Parameters
Type Name Description
StatusCodeRange[] forStatusCodes
Returns
Type Description
ApiRequest<T1, T2, T3, String>

ReceiveString(IEnumerable<StatusCodeRange>)

Declares that the response to this request may have an HTTP content which can be read as a raw string.

Declaration
public ApiRequest<T1, T2, T3, string> ReceiveString(IEnumerable<StatusCodeRange> forStatusCodes)
Parameters
Type Name Description
IEnumerable<StatusCodeRange> forStatusCodes

A set of status codes for which the HTTP content may be read as a raw string.
Returns
Type Description
ApiRequest<T1, T2, T3, String>

An ApiRequestBase, upgraded with the String type.
Exceptions
Type Condition
ArgumentNullException
  • forStatusCodes
ArgumentException

forStatusCodes is empty.

Implements

Extension Methods