WhateverDotNet.API.Abstractions 0.1.0-preview.6

WhateverDotNet.API.Abstractions

Abstractions and helpers for building JSON-based REST API clients, including:

• BaseJsonRestClient: reusable base class for sending JSON requests and deserializing JSON responses
• RequestSent / ResponseReceived events for custom API-call logging
• DI helpers to register logging utilities
• Test-execution logging abstractions (useful for NUnit / BDD-style step output)

Install

dotnet add package WhateverDotNet.API.Abstractions --prerelease

What's inside

• Base client: WhateverDotNet.API.Abstractions.BaseJsonRestClient
  • Sends requests via an initialized HttpClient
  • Serializes request bodies to JSON and deserializes responses from JSON
  • Raises RequestSent and ResponseReceived events for custom logging hooks
  • Optional structured tracing via ILogger<BaseJsonRestClient>
• Options: BaseJsonRestClientOptions (BaseUrl, Timeout)
• Events: CustomApiCallLoggerEventArgs (caller method, HTTP method, endpoint path, serialized payload)
• Logging:
  • ITestExecutionLogger (test output abstraction)
  • NUnitTestExecutionLogger (writes to Console)
  • ILogMessageFormatter / ApiLogMessageFormatter (human-readable step messages)
• DI: ServiceCollectionExtensions
  • AddApiLogMessageFormatter()
  • AddNUnitTestExecutionLogger(options)
• Exceptions: HttpClientNotInitializedException

Basic usage

Create your API client by inheriting from BaseJsonRestClient, call CreateClient to initialize the HttpClient, then use the Try*AsJsonAsync helpers.

using System.Net;

using FluentAssertions;

using Microsoft.Extensions.Logging;

using WhateverDotNet.API.Abstractions;
using WhateverDotNet.API.Abstractions.Logging;

public sealed class MyApiClient : BaseJsonRestClient
{
    public MyApiClient(
        BaseJsonRestClientOptions options,
        ILogMessageFormatter formatter,
        ITestExecutionLogger? testExecutionLogger,
        ILoggerFactory? loggerFactory = null)
        : base(options, loggerFactory)
    {
        if (testExecutionLogger is not null)
        {
            RequestSent += (_, args) =>
                testExecutionLogger.LogStep(
                    formatter.FormatLogMessage(
                        args.ClientMethodName,
                        args.HttpMethod,
                        args.EndpointPath,
                        args.SerializedPayload));
        }
    }

    public void ConnectAs(string bearerToken)
    {
        // The base class throws if BaseUrl/token are missing.
        CreateClient($"Bearer {bearerToken}");
    }

    public async Task<MyDto> GetSomethingAsync(CancellationToken cancellationToken = default)
    {
        (MyDto? response, HttpResponseMessage message) =
            await TryGetAsJsonAsync<MyDto>("/v1/something", cancellationToken: cancellationToken);

        message.StatusCode.Should().Be(HttpStatusCode.OK);
        response.Should().NotBeNull();

        return response!;
    }
}

public sealed record MyDto(string Id);

DI registration (optional)

using Microsoft.Extensions.DependencyInjection;

using WhateverDotNet.API.Abstractions.Extensions;
using WhateverDotNet.API.Abstractions.Logging;

var services = new ServiceCollection();

services.AddApiLogMessageFormatter();
services.AddNUnitTestExecutionLogger(new TestExecutionLoggerOptions
{
    StepPattern = "STEP: {0}",
    PreconditionPattern = "PRE: {0}",
    ExpectedResultPattern = "EXP: {0}",
    ActualResultPattern = "ACT: {0}",
});

Notes

• BaseJsonRestClient expects _httpClient to be initialized (for example via CreateClient(...)). If it isn't, calls throw HttpClientNotInitializedException.
• API-call logging is opt-in: subscribe to RequestSent / ResponseReceived and wire your own ITestExecutionLogger, telemetry, or other handlers.
• The default JSON serializer options use camelCase naming and are case-insensitive on property names.

Release notes

0.1.0-preview.6

• Breaking change: BaseJsonRestClient no longer accepts ILogMessageFormatter / ITestExecutionLogger in its constructor. Use the RequestSent and ResponseReceived events instead.
• Added CustomApiCallLoggerEventArgs and RequestSent / ResponseReceived events for extensible API-call logging.
• Added TryPostAsJsonAsync<TResponse> overload without a request body.
• CreateClient now throws ArgumentException (instead of ArgumentNullException) for blank tokens or missing base URLs.