Kanject.Core.Api.Abstractions 3.10.0

Kanject.Core.Api.Abstractions

Kanject.Core.Api.Abstractions holds the contract types shared by Kanject ASP.NET Core services and their service layers: the JSON response envelope and pagination models, the ApiResponseCode vocabulary, ApiServiceException, minimal-API result helpers, FluentValidation rules with XSS screening, and the identity interfaces the controller helpers build on.

Reference it directly from class libraries (services, validators, endpoint modules) that must speak the same response and error language as the web host without depending on a specific edge package. Kanject.Core.Api and Kanject.Core.ApiV2 both reference it, so web projects using either get it transitively.

Installation

dotnet add package Kanject.Core.Api.Abstractions

Targets .NET 8, .NET 9 and .NET 10, and is marked Native AOT / trimming compatible. It depends on Kanject.Core and FluentValidation, and uses ASP.NET Core types (IResult, ModelStateDictionary), so it is intended for ASP.NET Core applications and the libraries they call.

Quick start

A minimal-API endpoint that returns the standard envelope and signals an expected failure:

using Kanject.Core.Api.Abstractions.Endpoints;
using Kanject.Core.Api.Abstractions.Enums;
using Kanject.Core.Api.Abstractions.Exceptions;
using Kanject.Core.Api.Abstractions.Models;

app.MapGet("/api/orders/{id:guid}", async (Guid id, IOrderStore store, CancellationToken ct) =>
{
    var order = await store.FindAsync(id, ct)
        ?? throw new ApiServiceException("id", "The order does not exist.", ApiResponseCode.NotFound);

    return order.ApiResponse("Order retrieved.");
});

app.MapGet("/api/orders", async (int pageSize, string? pageToken, IOrderStore store, CancellationToken ct) =>
{
    var page = await store.ListAsync(pageSize, pageToken, ct);
    var metadata = new PayloadMetadata(pageSize, page.Items.Count, pageToken: page.NextToken);

    return page.Items.ApiResponse(metadata);
});

This package defines ApiServiceException but does not translate it into an HTTP response. The exception middleware in Kanject.Core.Api (Kanject envelope) or Kanject.Core.ApiV2 (Problem Details) does that; without one of them, register your own handler.

The response envelope

ResponseBase<T> / Response<T> serialize as:

{
  "data": { "id": "3f2c…" },
  "message": "Order retrieved.",
  "responseCode": "0",
  "status": 200
}

responseCode is a business code carried as a string — the numeric value of an ApiResponseCode by default, or any code you supply. status is a body field; the HTTP status of the response is set separately by whoever writes it (Results.Ok, a controller helper, the exception middleware).

Pagination

• PayloadMetadata (readonly struct) — PageSize, PageItemCount, PageToken, HasNextPage, Custom. The constructor sets HasNextPage = true whenever pageToken is non-empty (and not "{}"), so passing the continuation token is enough. PayloadMetadata.CreateEmpty(pageSize, pageToken) builds an empty page.
• ApiResponseDataset<T> — what paginated responses put in data: Dataset, PageSize, PageItemCount, PageToken, HasNextPage, Custom.
• PaginatedQueryModel — base class for requests with pageSize / pageToken.

Response codes

ApiResponseCode (namespace Kanject.Core.Api.Abstractions.Enums) is the shared business-code vocabulary. The value in responseCode is the member's number:

The HTTP status an edge package assigns is its own mapping — the exception middleware in Kanject.Core.Api / Kanject.Core.ApiV2 maps ValidationError → 400, Unauthorized → 401, NotFound → 404, Success → 200, and everything else → 500.

Exceptions

ExceptionKey and ResponseCode are exposed as properties for custom middleware.

Minimal-API helpers

Namespace Kanject.Core.Api.Abstractions.Endpoints — extension methods returning IResult:

Namespace Kanject.Core.Api.Abstractions.Extensions adds current-user helpers on ClaimsPrincipal and HttpContext: GetCurrentUserId(), GetCurrentUserOrganizationId(), GetCurrentUserGroups() and GetCurrentUserAsync(). They resolve your IUserIdentityClaimsPrincipal through the application builder registered with app.UseAppUtilityService(...) (from Kanject.Core), in a new scope created from the root provider.

Validation

FluentValidation rule extensions in Kanject.Core.Api.Abstractions.Extensions:

using FluentValidation;
using Kanject.Core.Api.Abstractions.Enums;
using Kanject.Core.Api.Abstractions.Extensions;

public sealed record CreateOrderRequest(string CustomerName, string Email, string Notes, string CallbackUrl);

public sealed class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderRequestValidator()
    {
        RuleFor(x => x.CustomerName).NotEmpty().MustMatchKnownNames();
        RuleFor(x => x.Email).MustBeValidEmailAddress();
        RuleFor(x => x.Notes).MustBeSafeFromXss(XssValidationMode.Standard, maxLength: 2000);
        RuleFor(x => x.CallbackUrl).MustBeValidUrl(allowedSchemes: ["https"]);
    }
}

XssValidationMode: Strict, Standard (the default), Html, Markdown, Custom. The built-in character sets are ASCII-only and exclude line breaks, so accented letters, non-Latin scripts and multi-line text fail every mode except Custom with your own character set.

To surface FluentValidation results through MVC model state, use ModelState.TryAddValidationErrors(validationResult) — property names are camel-cased as keys. Overloads also merge another ModelStateDictionary or a ValidationProblemDetails. GetValidationErrors() joins all messages with ", ".

Service-layer and identity contracts

• IService / AbstractService — a disposable service base that accumulates errors in a ModelStateDictionary (Errors, HasError) alongside ResponseCode, StatusCode and ResponseMessage, for services that report failures instead of throwing.
• IUserIdentityClaimsPrincipal — implement it for your identity provider: GetUserId, GetUserGroups, GetUserPermissions, GetUserIdentityInformation. The current-user helpers here and in Kanject.Core.Api / Kanject.Core.ApiV2 call it.
• IApplicationUser, IApplicationUserGroup — user and group shapes returned by that reader.
• HttpRequestLoggerExtensions.LogHttpRequestAsync(request, exception) — prints the URL, verb, headers (except Authorization), full request body, and exception details to the console. The edge packages call it for unhandled exceptions; mind personal data in bodies and cookies.

Attributes for generated minimal APIs

[ApiEndpoints] and the [HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch] attributes in Kanject.Core.Api.Abstractions.Attributes describe minimal-API endpoint groups as static classes. They do nothing on their own — add the Kanject.Core.Api.Annotations source generator to turn them into route registrations. These verb attributes are distinct from the MVC attributes of the same names in Microsoft.AspNetCore.Mvc.

Related packages

License

Licensed under the Kanject Code Libraries License Agreement (KCLLA); the full text ships in this package as LICENSE.md. Organizations whose trailing-twelve-month gross revenue and total funding raised are each below US$250,000 may use it at no cost under the Free Tier. At or above either threshold a commercial license is required — contact commercial@kanjectbusiness.com.