KeyInteractive.Common.Api 2.0.0

Key Interactive.Common.Api

KeyInteractive.Common.Api is the generic plumbing to build .NET clients for Key Interactive-style APIs: a standard response envelope, an idempotent-only retry policy with exponential backoff, JWT access + rotating refresh token handling, and the conventional Key Interactive request headers.

It ships no endpoints of its own — it's the base your own API consumer inherits from. For the official client of the Key Interactive Users API, see KeyInteractive.Common.Api.Users.

What's in it

• KiApiResponse / KiApiResponseData — the standard response envelope (Success, ResponseCode, ErrorMessage, optionally Data). Every consumer method built on this package returns one of these — callers branch on Success, never on a caught exception: network/HTTP/JSON failures are turned into a synthetic error response, never thrown.
• ITokenProvider / TokenProvider — holds the JWT access + refresh token for one consumer instance. Register it Scoped in Blazor Server (one instance per circuit); never make an implementation of ITokenProvider static, or tokens leak between users of the same process after a SignalR reconnect.
• KiApiConsumerOptions — per-instance configuration (base URI, optional API key/application key, API version segment, token storage key prefix, device info, timeout).
• IKiApiConsumer — the minimal interface every consumer implements (SetSiteBaseUrl/SetSiteLanguage).
• KiApiConsumerBase — the abstract base class. Handles the HttpClient lifecycle, retry, token rotation, and conventional headers; exposes GetAsync/PostAsync/PutAsync/DeleteAsync helpers so each endpoint in your derived consumer is a one-liner.

Installation

dotnet add package KeyInteractive.Common.Api

Building your own API consumer

using KeyInteractive.Common.Api;

public class MyApiConsumer : KiApiConsumerBase, IMyApiConsumer
{
    public MyApiConsumer(HttpClient? httpClient = null, ITokenProvider? tokenProvider = null, IJSRuntime? jsRuntime = null)
        : base(httpClient, new KiApiConsumerOptions
        {
            BaseUri = "https://my-api.example.com/",
            ApiKey = "your-api-key",           // optional: omit (leave null) to skip the header entirely
            ApplicationKey = "your-app-id",     // optional, same as above
            ApiVersion = "v1",                  // path segment, defaults to "v1"
            StorageKeyPrefix = "myapi",         // must be unique per consumer in the same site
        }, tokenProvider, jsRuntime)
    {
    }

    public Task<APIThingResponse> GetThing(int id) =>
        GetAsync<APIThingResponse>($"Thing/{id}");

    // Not idempotent by default: safe against double-submission on retry.
    public Task<KiApiResponse> DoStuff(StuffDto dto) =>
        PostAsync<KiApiResponse>("Thing/DoStuff", dto);

    // Pass isIdempotent: true only for endpoints that are genuinely safe to retry
    // automatically (e.g. a read-only server-to-server lookup implemented as a POST).
    public Task<APIThingResponse> LookupThing(LookupDto dto) =>
        PostAsync<APIThingResponse>("Thing/Lookup", dto, isIdempotent: true);
}

APIThingResponse is any class deriving from KiApiResponse (or KiApiResponseData if you need a generic payload wrapper).

Response envelope

Every call returns a KiApiResponse-derived type — check Success, never rely on an exception:

var result = await myApiConsumer.GetThing(42);

if (result.Success)
{
    // use result.Thing (or whatever fields your APIThingResponse adds)
}
else
{
    Console.WriteLine(result.ErrorMessage);
}

Dependency injection (Blazor Server)

// Program.cs
builder.Services.AddScoped<ITokenProvider, TokenProvider>();
builder.Services.AddHttpClient<IMyApiConsumer, MyApiConsumer>();

If a single site talks to two different APIs built on this package (e.g. the Users API plus your own), register two distinct typed HttpClients and give each KiApiConsumerOptions its own StorageKeyPrefix — otherwise both consumers would fight over the same {prefix}_auth_token/{prefix}_auth_refresh_token storage keys. If the two APIs also have independent login sessions, register two separate ITokenProvider implementations too (e.g. via keyed services or two marker interfaces), rather than sharing one.

Behavior you can rely on

• Retry: automatic only for idempotent calls (GetAsync, or PostAsync/PutAsync/DeleteAsync explicitly marked isIdempotent: true), with exponential backoff, and only on 408/429/502/503/504 or a network-level HttpRequestException. Non-idempotent POSTs fail on the first error — retrying after the server already processed the request would risk duplicating its effect.
• Refresh token rotation: applied from the response headers before branching on success/error, since the API may rotate the refresh token on a request it still rejects (e.g. wrong password). Optionally persisted to localStorage/sessionStorage via IJSRuntime, if one is provided.
• No exceptions from network/HTTP/JSON failures: they're translated into a normal KiApiResponse with Success = false.