The Windows program as a client of the API

dotnet new classlib -n Brandt.OrderBook.Client -f net10.0
Remove-Item Brandt.OrderBook.Client/Class1.cs
dotnet sln Brandt.OrderBook.sln add Brandt.OrderBook.Client/Brandt.OrderBook.Client.csproj
dotnet add Brandt.OrderBook.Client/Brandt.OrderBook.Client.csproj reference Brandt.OrderBook.Contracts/Brandt.OrderBook.Contracts.csproj
dotnet add Brandt.OrderBook.Client/Brandt.OrderBook.Client.csproj package Microsoft.Extensions.Http.Resilience --version "10.*"
dotnet add Brandt.OrderBook/Brandt.OrderBook.csproj reference Brandt.OrderBook.Client/Brandt.OrderBook.Client.csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <TargetFramework>net10.0</TargetFramework>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="10.*" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\Brandt.OrderBook.Contracts\Brandt.OrderBook.Contracts.csproj" />
  </ItemGroup>

</Project>

namespace Brandt.OrderBook.Client;

public enum ApiErrorKind
{
    Unreachable,
    TimedOut,
    NotFound,
    Conflict,
    Invalid,
    ServerError,
    Unexpected,
}

public sealed record ApiError(ApiErrorKind Kind, string Message, IReadOnlyDictionary<string, string[]>? Fields = null);

// Expected errors are a result, not an exception: A form has to be able to show them without try/catch at every place.
public sealed class ApiResult<T>
{
    private readonly T? _value;

    private ApiResult(T? value, ApiError? error)
    {
        _value = value;
        Error = error;
    }

    public ApiError? Error { get; }

    public bool IsOk => Error is null;

    public T Value => IsOk ? _value! : throw new InvalidOperationException(Error!.Message);

    public static ApiResult<T> Success(T value) => new(value, null);

    public static ApiResult<T> Failure(ApiError error) => new(default, error);
}

using System.Net;
using System.Net.Http.Json;
using System.Text.Json;
using Brandt.OrderBook.Logic;
using Brandt.OrderBook.Contracts;
using Polly.Timeout;

namespace Brandt.OrderBook.Client;

public interface IOrderApi
{
    Task<ApiResult<OrdersPage>> ReadAsync(OrderStatus? status, int page, int pageSize, CancellationToken ct = default);

    Task<ApiResult<OrderDetailDto>> ReadOneAsync(int orderId, CancellationToken ct = default);

    Task<ApiResult<OrderDetailDto>> ChangeAsync(int orderId, OrderChangeDto change, CancellationToken ct = default);

    Task<ApiResult<BillingDto>> BillAsync(int orderId, CancellationToken ct = default);
}

public sealed class OrderApiClient(HttpClient http) : IOrderApi
{
    private static readonly JsonSerializerOptions Json = ContractJson.New();

    public Task<ApiResult<OrdersPage>> ReadAsync(OrderStatus? status, int page, int pageSize, CancellationToken ct = default)
    {
        string query = $"page={page}&pageSize={pageSize}" + (status is { } chosen ? $"&status={chosen}" : string.Empty);
        return SendAsync<OrdersPage>(() => http.GetAsync($"api/v1/orders?{query}", ct), ct);
    }

    public Task<ApiResult<OrderDetailDto>> ReadOneAsync(int orderId, CancellationToken ct = default) =>
        SendAsync<OrderDetailDto>(() => http.GetAsync($"api/v1/orders/{orderId}", ct), ct);

    public Task<ApiResult<OrderDetailDto>> ChangeAsync(int orderId, OrderChangeDto change, CancellationToken ct = default) =>
        SendAsync<OrderDetailDto>(() => http.PutAsJsonAsync($"api/v1/orders/{orderId}", change, Json, ct), ct);

    public Task<ApiResult<BillingDto>> BillAsync(int orderId, CancellationToken ct = default) =>
        SendAsync<BillingDto>(() => http.PostAsync($"api/v1/orders/{orderId}/billing", null, ct), ct);

    private static async Task<ApiResult<T>> SendAsync<T>(Func<Task<HttpResponseMessage>> send, CancellationToken ct)
    {
        try
        {
            using HttpResponseMessage response = await send();
            if (!response.IsSuccessStatusCode)
            {
                return ApiResult<T>.Failure(await ReadErrorAsync(response, ct));
            }

            T? value = await response.Content.ReadFromJsonAsync<T>(Json, ct);
            return value is null
                ? ApiResult<T>.Failure(new ApiError(ApiErrorKind.Unexpected, "The response of the API was empty."))
                : ApiResult<T>.Success(value);
        }
        catch (TimeoutRejectedException)
        {
            // The timeout of the resilience layer (see the registration).
            return ApiResult<T>.Failure(new ApiError(ApiErrorKind.TimedOut, "The API did not respond in time."));
        }
        catch (TaskCanceledException) when (!ct.IsCancellationRequested)
        {
            // HttpClient.Timeout: a TaskCanceledException that the caller did not trigger.
            return ApiResult<T>.Failure(new ApiError(ApiErrorKind.TimedOut, "The API did not respond in time."));
        }
        catch (HttpRequestException ex)
        {
            return ApiResult<T>.Failure(new ApiError(ApiErrorKind.Unreachable, "The API is not reachable: " + ex.Message));
        }
        catch (JsonException)
        {
            return ApiResult<T>.Failure(new ApiError(ApiErrorKind.Unexpected, "The response of the API is not readable."));
        }
    }

    private static async Task<ApiError> ReadErrorAsync(HttpResponseMessage response, CancellationToken ct)
    {
        ProblemResponse? problem = null;
        try
        {
            problem = await response.Content.ReadFromJsonAsync<ProblemResponse>(Json, ct);
        }
        catch (JsonException)
        {
            // Not problem JSON, for example the error page of a proxy: It stays with the status code.
        }

        string message = problem?.Title ?? $"The API answered with {(int)response.StatusCode}.";
        ApiErrorKind kind = response.StatusCode switch
        {
            HttpStatusCode.NotFound => ApiErrorKind.NotFound,
            HttpStatusCode.Conflict => ApiErrorKind.Conflict,
            HttpStatusCode.BadRequest or HttpStatusCode.UnprocessableEntity => ApiErrorKind.Invalid,
            >= HttpStatusCode.InternalServerError => ApiErrorKind.ServerError,
            _ => ApiErrorKind.Unexpected,
        };
        return new ApiError(kind, message, problem?.Errors);
    }

    // The API's problem JSON (RFC 9457), as far as the client needs it.
    private sealed record ProblemResponse(string? Title, string? Detail, int? Status, Dictionary<string, string[]>? Errors);
}