NowAround.SharedKernel.Contracts

Shared HTTP contract types for NowAround services.

Features

• Cursor pagination request model.
• Cursor pagination response model.
• Link metadata for current, next, and previous pages.
• Validation attributes for common HTTP input constraints.

Installation

dotnet add package NowAround.SharedKernel.Contracts

Cursor Pagination

Use CursorPageRequest for endpoints that accept cursor-based pagination:

using NowAround.SharedKernel.Contracts.Http.Pagination;

app.MapGet("/items", async ([AsParameters] CursorPageRequest request) =>
{
    int limit = request.Limit ?? 25;
    string? cursor = request.Cursor;

    // Query one page of data and calculate the next cursor.
});

CursorPageRequest contains:

• Limit: optional page size. Valid range is 1 through 100.
• Cursor: optional opaque cursor. Maximum length is 512 characters.

Return CursorPageResponse<TItem> from APIs that expose cursor-based lists:

var response = new CursorPageResponse<ItemDto>(
    Items: items,
    PageInfo: new CursorPageInfo(
        PageSize: items.Count,
        HasNextPage: nextCursor is not null,
        NextCursor: nextCursor),
    Links: new CursorPageLinks(
        Self: currentUrl,
        Next: nextUrl));

CursorPageResponse<TItem> contains:

• Items: current page data.
• PageInfo: page size, next-page flag, and next cursor.
• Links: optional navigation URLs.

Contract Rules

Keep cursors opaque to consumers. Services may encode internal ordering, filters, or continuation state, but clients should only pass the cursor value back to the API.