REST API Design Best Practices with ASP.NET Core

using System.Text;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.WebUtilities;
using Microsoft.EntityFrameworkCore;

app.MapGet("/api/orders", async Task<Results<Ok<Page<OrderSummary>>, ProblemHttpResult>> (
    string? cursor, int? limit, ShopDbContext db, CancellationToken ct) =>
{
    var pageSize = Math.Clamp(limit ?? 25, 1, 100);
    IQueryable<Order> query = db.Orders.AsNoTracking();

    if (cursor is not null)
    {
        if (!OrderCursor.TryDecode(cursor, out var after))
        {
            return TypedResults.Problem(statusCode: 400, title: "The cursor is invalid.");
        }

        query = query.Where(o => o.CreatedAt > after.CreatedAt
            || (o.CreatedAt == after.CreatedAt && o.Id > after.Id));
    }

    var rows = await query
        .OrderBy(o => o.CreatedAt).ThenBy(o => o.Id)
        .Take(pageSize + 1) // One extra row reveals whether another page exists
        .Select(o => new OrderSummary(o.Id, o.CreatedAt, o.Total))
        .ToListAsync(ct);

    var hasMore = rows.Count > pageSize;
    var items = hasMore ? rows.GetRange(0, pageSize) : rows;
    var next = hasMore ? new OrderCursor(items[^1].CreatedAt, items[^1].Id).Encode() : null;
    return TypedResults.Ok(new Page<OrderSummary>(items, next));
});

public sealed record Page<T>(IReadOnlyList<T> Items, string? NextCursor);

public readonly record struct OrderCursor(DateTimeOffset CreatedAt, Guid Id)
{
    public string Encode() =>
        WebEncoders.Base64UrlEncode(Encoding.UTF8.GetBytes($"{CreatedAt.UtcTicks}:{Id}"));

    public static bool TryDecode(string value, out OrderCursor cursor)
    {
        cursor = default;
        try
        {
            var parts = Encoding.UTF8.GetString(WebEncoders.Base64UrlDecode(value)).Split(':');
            if (parts.Length != 2 || !long.TryParse(parts[0], out var ticks)
                || !Guid.TryParse(parts[1], out var id))
            {
                return false;
            }

            cursor = new(new DateTimeOffset(ticks, TimeSpan.Zero), id);
            return true;
        }
        catch (FormatException)
        {
            return false;
        }
    }
}