SKitLs.ClientsApi.Core 1.0.1

SKitLs.ClientsApi.Core

Lightweight base library for building JSON-based HTTP API clients on top of HttpClient.

The goal of this project is to remove boilerplate code when implementing API clients, while keeping behavior explicit, predictable and easy to customize.

Features

• Unified HTTP request pipeline
• Built-in JSON serialization and deserialization
• Automatic query string building from DTOs or dictionaries
• Consistent error handling via ApiException
• Minimal abstractions, no framework-level magic
• Fully testable without real HTTP calls

When to use

This library is a good fit if you:

• write multiple HTTP API clients
• want consistent error handling and serialization
• prefer explicit code over heavy frameworks
• want full control over HttpClient configuration

This is not a REST framework and does not rely on code generation or reflection-based routing.

Basic usage

1. Create a client

public sealed class MyApiClient : JsonApiClientBase
{
    protected override void ConfigureHttpClient(HttpClient client)
    {
        client.BaseAddress = new Uri("https://api.example.com/");
        client.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "token");
    }

    public Task<UserDto?> GetUser(int id, CancellationToken ct = default)
        => GetAsync<UserDto>($"users/{id}", ct: ct);

    public Task<UserDto?> CreateUser(CreateUserDto dto, CancellationToken ct = default)
        => PostAsync<CreateUserDto, UserDto>("users", dto, ct: ct);
}

Query parameters

Query parameters can be provided as an object or a dictionary (Dictionary<string, object?>).

DTO-based query

var users = await client.GetAsync<UserDto[]>(
    "users",
    new { page = 1, pageSize = 20 });

Dictionary-based query

var users = await client.GetAsync<UserDto[]>(
    "users",
    new Dictionary<string, object>
    {
        ["status"] = "active",
        ["page"] = 2
    });

Null values are ignored automatically.

Error handling

Non-success HTTP responses result in an ApiException:

try
{
    await client.GetAsync<UserDto>("users/unknown");
}
catch (ApiException ex)
{
    Console.WriteLine(ex.StatusCode);
    Console.WriteLine(ex.RequestUri);
    Console.WriteLine(ex.RawResponse);
}

Customization points

You can override the following methods to customize behavior:

• ConfigureHttpClient
• CreateSerializer
• BuildRequestUri
• BuildQueryString
• OnBeforeSendAsync
• OnAfterResponseAsync
• CreateApiExceptionAsync

Design principles

• Explicit over implicit
• No hidden retries or policies
• No dependency on DI frameworks
• Minimal surface area
• Easy to reason about and debug

License

MIT Copyright (c) 2026 SKitLs