Requests

Requests

RestlingClient provides convenience methods for common REST operations and execution methods for advanced request objects.

GET

Return response metadata and content without deserializing a model:

RestRequestResult result = await client.GetAsync(uri, cancellationToken);

Deserialize the response into a model:

RestRequestResult<Customer> result = await client.GetAsync<Customer>(
    uri,
    cancellationToken: cancellationToken);

POST and PUT

Send a request model without requiring a typed response:

RestRequestResult result = await client.PostAsync(
    uri,
    requestData,
    cancellationToken: cancellationToken);

Send one model and deserialize another:

RestRequestResult<Customer> result = await client.PostAsync<Customer, CreateCustomerRequest>(
    uri,
    requestData,
    cancellationToken: cancellationToken);

RestRequestResult<Customer> updated = await client.PutAsync<Customer, UpdateCustomerRequest>(
    uri,
    updateData,
    cancellationToken: cancellationToken);

DELETE

RestRequestResult result = await client.DeleteAsync(uri, cancellationToken);

RestRequestResult<DeleteReceipt> typedResult = await client.DeleteAsync<DeleteReceipt>(
    uri,
    cancellationToken: cancellationToken);

All GET, POST, PUT, and DELETE operations also have overloads that accept RequestHeaders.

Generic request objects

Use RestRequest to select the HTTP method at runtime or to send a custom method:

RestRequest request = new(uri, AMDevIT.Restling.Core.HttpMethod.Get);

RestRequestResult<Customer> result = await client.ExecuteRequestAsync<Customer>(
    request,
    cancellationToken: cancellationToken);

To send a custom verb, select HttpMethod.Custom and provide the verb name:

RestRequest request = new(
    uri,
    AMDevIT.Restling.Core.HttpMethod.Custom,
    customMethod: "PATCH");

For a typed payload, use RestRequest<TRequest>:

RestRequest<UpdateCustomerRequest> request = new(
    uri,
    AMDevIT.Restling.Core.HttpMethod.Put,
    requestData);

RestRequestResult<Customer> result = await client.ExecuteRequestAsync<Customer, UpdateCustomerRequest>(
    request,
    cancellationToken: cancellationToken);

Set ContentMediaType when the server requires a specific payload content type.

Raw requests

Use RestRawRequest when the body is already serialized or must be sent verbatim:

using AMDevIT.Restling.Core.Network;

RestRawRequest request = new(
    uri,
    AMDevIT.Restling.Core.HttpMethod.Post,
    content: json,
    contentType: HttpMediaType.ApplicationJson)
{
    AcceptType = HttpMediaType.ApplicationJson
};

RestRequestResult<ApiResponse> result = await client.ExecuteRawRequestAsync<ApiResponse>(
    request,
    cancellationToken: cancellationToken);

Form URL-encoded requests

IDictionary<string, string> fields = new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["scope"] = "api.read"
};

FormUrlEncodedRequest request = new(
    uri,
    AMDevIT.Restling.Core.HttpMethod.Post,
    fields);

RestRequestResult<TokenResponse> result = await client.ExecuteFormUrlEncodedRequest<TokenResponse>(
    request,
    cancellationToken: cancellationToken);

Binary responses

Request a byte array to download binary content:

RestRequestResult<byte[]> result = await client.GetAsync<byte[]>(
    downloadUri,
    cancellationToken: cancellationToken);

if (result.IsSuccessful && result.Data is not null)
{
    await File.WriteAllBytesAsync(destinationPath, result.Data, cancellationToken);
}

See Serialization for payload selection and Headers and Authentication for request-specific headers.