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.