ApiPilot.AspNetCore 1.0.6

dotnet add package ApiPilot.AspNetCore --version 1.0.6
                    
NuGet\Install-Package ApiPilot.AspNetCore -Version 1.0.6
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ApiPilot.AspNetCore" Version="1.0.6" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ApiPilot.AspNetCore" Version="1.0.6" />
                    
Directory.Packages.props
<PackageReference Include="ApiPilot.AspNetCore" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ApiPilot.AspNetCore --version 1.0.6
                    
#r "nuget: ApiPilot.AspNetCore, 1.0.6"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ApiPilot.AspNetCore@1.0.6
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ApiPilot.AspNetCore&version=1.0.6
                    
Install as a Cake Addin
#tool nuget:?package=ApiPilot.AspNetCore&version=1.0.6
                    
Install as a Cake Tool

ApiPilot

ApiPilot.Core ApiPilot.AspNetCore ApiPilot.Security License: MIT .NET 10 Build

A contract-first API boundary for ASP.NET Core. Consistent JSON envelopes, stable error codes, validation, pagination, correlation, CSRF issuance and validation, secure cookie profiles, Origin and Fetch Metadata policy, a repository-owned OpenAPI emitter, rate-limit integration, diagnostics, and a zero-runtime-dependency browser client - in one library with a cross-language wire specification.

Target: .NET 10 | License: MIT | Runtime dependencies: none | Releases: https://github.com/sancy1/ApiPilot/releases


Why ApiPilot

Every professional API re-invents the same boundary conventions - and each service re-invents them differently.

  • Response envelopes that differ per endpoint.
  • Error codes that mean different things in different services.
  • Validation responses that differ between MVC controllers and minimal APIs.
  • Pagination conventions that drift (page vs pageNumber, pageSize vs perPage).
  • Correlation IDs that appear in some responses and not others.
  • CSRF protection that is hand-rolled, inconsistently, or missing.
  • Browser clients that cannot share a stable parser across services.

The result: client SDKs cannot be reused, security defaults drift, and every new service is a new integration.

ApiPilot standardizes the boundary once. Applications adopt the conventions they want - the envelope, the error contract, pagination, correlation, the security surfaces - and plug in the rest. The wire contract is documented in SPEC.md and is shared across every language binding.


The wire contract

Every response is a JSON object with a top-level success discriminator.

Success

{
  "success": true,
  "data": { "id": "ORD-10001", "status": "confirmed" },
  "message": "Order retrieved successfully.",
  "meta": {
    "requestId": "01J8Z3K7X9Y2F0A6M3N5P7Q1R2",
    "timestamp": "2026-09-29T00:00:00Z",
    "extra": {}
  }
}

success and data are required. message and meta are always present - message is null when the application provides none; meta always carries requestId, timestamp, and extra.

Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more values are invalid.",
    "fields": { "email": [ "Email is required." ] }
  },
  "meta": { "requestId": "01J8Z3K7X9Y2F0A6M3N5P7Q1R2" }
}

error.code is a stable, machine-readable identifier from the table below.

Error codes

Condition HTTP status Code
Validation failure 400 or 422 VALIDATION_ERROR
Authentication missing 401 AUTHENTICATION_REQUIRED
Authorization failure 403 FORBIDDEN
Missing CSRF header 403 CSRF_HEADER_MISSING
Invalid CSRF token 403 CSRF_TOKEN_INVALID
Expired CSRF token 403 CSRF_TOKEN_EXPIRED
Origin rejected 403 CSRF_ORIGIN_REJECTED
Resource not found 404 RESOURCE_NOT_FOUND
Conflict 409 CONFLICT
Rate limited 429 RATE_LIMITED
Unknown exception 500 INTERNAL_ERROR
Configuration error startup CONFIGURATION_ERROR
Unacceptable Accept 406 NOT_ACCEPTABLE
Unsupported content type 415 UNSUPPORTED_MEDIA_TYPE

Default exception mapping

When an exception escapes an endpoint protected by UseApiPilotExceptions, the middleware maps it to an error envelope using the following default table, in match order. The first matching entry wins.

Exception type error.code HTTP status
ArgumentNullException VALIDATION_ERROR 400
ArgumentException VALIDATION_ERROR 400
KeyNotFoundException RESOURCE_NOT_FOUND 404
UnauthorizedAccessException FORBIDDEN 403
InvalidOperationException CONFLICT 409
any other exception INTERNAL_ERROR 500

Applications can replace or extend the table through ApiExceptionOptions.Mappings. Applications can override the HTTP status produced for any wire code through ApiExceptionOptions.ErrorCodeToStatusMap.

Paginated collections

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "pageSize": 20,
    "totalItems": 143,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": true
  },
  "meta": { "requestId": "01J8Z3K7X9Y2F0A6M3N5P7Q1R2" }
}

The full contract is in SPEC.md.


Quick start

The three packages are published on NuGet. Install them directly:

dotnet add package ApiPilot.Core
dotnet add package ApiPilot.AspNetCore
dotnet add package ApiPilot.Security

1. Register ApiPilot services

using ApiPilot.AspNetCore.Middleware;
using ApiPilot.AspNetCore.Serialization;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApiPilotJson();
builder.Services.AddApiPilotCorrelation();
builder.Services.AddApiPilotExceptions();
builder.Services.AddApiPilotPagination();

2. Add the middleware in the documented order

var app = builder.Build();

// The pipeline order is required. Each component depends on the ones before it.
app.UseApiPilotCorrelation();  // establishes the request id first
app.UseApiPilotExceptions();   // maps a fault anywhere downstream
app.UseRouting();              // the CSRF middleware reads endpoint metadata
app.UseRateLimiter();          // the application-owned limiter (see below)

app.MapControllers();
app.Run();

3. Return the envelope from an endpoint

using ApiPilot.AspNetCore.Results;
using ApiPilot.Core.Metadata;
using ApiPilot.Core.Responses;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;

app.MapGet("/api/orders/{id}", (HttpContext context, string id) =>
{
    var accessor = context.RequestServices.GetService<ICorrelationIdAccessor>();
    var meta = new ResponseMetadata
    {
        RequestId = accessor?.RequestId ?? context.TraceIdentifier
    };

    var order = new { id, status = "confirmed" };
    return ApiResponseBuilder.Ok(order, meta).ToResult();
});

ApiResponseBuilder.Ok<T>(data, meta, message?) builds the success envelope; .ToResult() writes it to the HTTP response with the correct status code.

4. Errors map automatically

An unhandled exception in an endpoint - with UseApiPilotExceptions() in the pipeline - becomes the standard error envelope. The client always sees a success: false body with a stable error.code, never a stack trace.


Capability table

Explicit states: Built in - one call and it works. Partial - the framework provides a piece; ApiPilot standardizes the rest. Manual - the application writes it. Not built in - does not exist and is not attempted.

Capability ApiPilot ASP.NET Core alone Application work
Success envelope Built in Not standardized Manual
Error codes & status mapping Built in Partial Manual
Validation envelope Built in Partial Manual
Pagination contract Built in Not built in Manual
Filtering & sorting metadata Built in Not built in Manual
Correlation IDs Built in Not standardized Manual
Content negotiation (406/415) Built in Partial Manual
CSRF issuance & validation Built in Not built in Manual
Secure cookie profiles Built in Not standardized Manual
Origin policy Built in Not built in Manual
Fetch Metadata Built in Not built in Manual
OpenAPI document Built in (repository-owned emitter) Partial metadata APIs Configure endpoints
Rate-limit rejection envelope Built in (adapter) Built in (the limiter) Configure the policy
Browser client Built in (zero runtime deps) Not built in Manual
Retry / circuit breaker / idempotency Not included Not built in Use a resilience library
Authentication / authorization Not included Built in (Identity, JwtBearer) Application owns it
Database access / caching Not included Not built in Application owns it

On rate limiting: ApiPilot does not implement a limiter. It integrates with the ASP.NET Core rate limiter through RateLimiterOptions.OnRejected. The application configures the limiter and the policy; ApiPilot supplies the rejection handler and the standard RATE_LIMITED envelope.


Packages

Package Purpose
ApiPilot.Core framework-independent contracts: the envelope, the error model, validation, pagination, correlation abstractions. Depends only on the .NET BCL.
ApiPilot.AspNetCore the ASP.NET Core adapter: middleware, filters, results, serialization, content negotiation, OpenAPI emitter, rate-limit rejection.
ApiPilot.Security CSRF issuance and validation, secure cookie profiles, Origin policy, Fetch Metadata, Data Protection integration.
@apipilot/client zero-runtime-dependency browser fetch client.

Install only the layers an application needs. A service that only needs the envelope and error contract references ApiPilot.Core alone.


Documentation

Each concern has a per-concern document. The full list is in docs/README.md.

Concern Document
The success / error / paginated envelopes docs/response-contract.md
The error model and code table docs/error-contract.md
Validation, field normalization docs/validation.md
Pagination and query parameters docs/pagination.md
Filtering and sorting docs/filtering-sorting.md
JSON policy docs/serialization.md
Content negotiation (406 / 415) docs/content-negotiation.md
Correlation IDs docs/correlation.md
CSRF protection docs/csrf.md
Unsafe-method protection docs/unsafe-methods.md
Secure cookie profiles docs/cookies.md
Origin policy docs/origin-policy.md
Fetch Metadata docs/fetch-metadata.md
Data Protection and multi-instance docs/data-protection.md, docs/multi-instance.md
OpenAPI emitter docs/openapi.md
Rate-limit integration docs/rate-limiting.md
Observability docs/observability.md
Threat model docs/threat-model.md
Browser client docs/fetch-helper.md
Supply chain (SBOM, signing, provenance) docs/supply-chain.md
Deployment docs/deployment.md
Troubleshooting a 403 docs/troubleshooting-403.md
Migration docs/migration.md
Resilience companion integration docs/resilience-integration.md

The single normative document is SPEC.md.


Architecture

The request boundary

HTTP request
    |
    v
ASP.NET Core pipeline
    |
    +--> UseApiPilotCorrelation   (assign / validate the request id)
    +--> UseApiPilotExceptions    (map a fault to the error envelope)
    +--> UseRouting
    +--> UseApiPilotCsrfProtection (validate CSRF on unsafe methods)
    +--> UseRateLimiter           (application-owned limiter)
    |
    v
application endpoint
    |
    +--> external calls (application-selected resilience library)
    |
    v
ApiPilot result  OR  mapped error
    |
    v
standard JSON envelope  +  diagnostics

Package boundaries

ApiPilot.Core
    |
    +--> ApiPilot.AspNetCore
    |
    +--> ApiPilot.Security
    |
    +--> @apipilot/client (JavaScript; consumes the same wire contract)

ApiPilot.Core has no HTTP dependency. ApiPilot.AspNetCore and ApiPilot.Security depend on ASP.NET Core. The client is standalone.


Security surfaces

ApiPilot implements the defense-in-depth layers a cookie-authenticated API needs. Each is documented in its per-concern doc.

CSRF - the two-credential model

The authentication cookie is HttpOnly and Secure - browser-managed and unreadable by JavaScript. CSRF uses a separate request token, held in memory by the client and sent in a custom header on protected methods.

// Server: register CSRF services and the pipeline component.
builder.Services.AddDataProtection();
builder.Services.AddApiPilotCsrf();

var app = builder.Build();
app.UseApiPilotCorrelation();
app.UseApiPilotExceptions();
app.UseRouting();
app.UseApiPilotCsrfProtection();
app.UseRateLimiter();

// Expose the bootstrap endpoint (GET /api/csrf by default).
app.MapApiPilotCsrf();

POST, PUT, PATCH, and DELETE require the CSRF header by default. A [ApiPilotSkipCsrf] endpoint opts out; a [ApiPilotRequireCsrf] endpoint opts in.

Origin and Fetch Metadata

builder.Services.AddApiPilotOriginPolicy();
builder.Services.AddApiPilotFetchMetadata();

app.UseApiPilotOriginPolicy();
app.UseApiPilotFetchMetadata();

Both run before the CSRF middleware. Origin policy is defense in depth; the CSRF token is the primary protection.

builder.Services.AddApiPilotCookies();

The cookie profile validator rejects an insecure combination at startup: SameSite=None requires Secure=true; __Host- requires Secure, no Domain, and Path=/.


Pagination

Register the pagination options once, then opt endpoints in:

using ApiPilot.AspNetCore.EndpointMetadata;
using ApiPilot.Core.Pagination;

// Global configuration (application-wide).
builder.Services.AddApiPilotPagination(o =>
{
    o.DefaultPageSize = 25;
    o.MaxPageSize     = 200;
});

// Per-endpoint opt-in (minimal API).
app.MapGet("/api/items", (HttpContext context) =>
{
    var page = context.GetPageRequest();
    return Results.Ok();
})
.WithApiPilotPagination(o =>
{
    o.MaxPageSize = 50;  // fluent override
});

The precedence chain is global options → fluent overrides → the [PaginationMetadata] attribute.


Correlation

builder.Services.AddApiPilotCorrelation(o =>
{
    o.HeaderName = "X-Correlation-Id";  // default is X-Request-Id
});

app.UseApiPilotCorrelation();

Every response envelope carries meta.requestId. The ID is read from the configured header, validated against a pattern, and generated when absent or malformed.


OpenAPI

ApiPilot ships a repository-owned OpenAPI 3.0.3 emitter. It reads the framework ApiExplorer descriptors and writes a document with System.Text.Json. No Microsoft.OpenApi, Swashbuckle, NSwag, or Swagger package is referenced.

builder.Services.AddApiPilotOpenApi(o =>
{
    o.DocumentTitle   = "Orders API";
    o.DocumentVersion = "1.0.0";  // your API's version, not the library version
    o.DocumentPath    = "/openapi/v1.json";  // the default
});

var app = builder.Build();
app.MapApiPilotOpenApi();

Rate limiting

ApiPilot does not implement a limiter. It integrates with the ASP.NET Core limiter through the platform own extension point:

builder.Services.AddApiPilotRateLimitRejection();

builder.Services.AddRateLimiter(o =>
{
    o.OnRejected = RateLimitDiagnosticsHook.HandleAsync;  // the ApiPilot handler
    o.AddFixedWindowLimiter("api", w =>
    {
        w.PermitLimit = 100;
        w.Window      = TimeSpan.FromSeconds(60);
    });
});

app.UseRateLimiter();

A rejection produces the standard envelope with error.code = "RATE_LIMITED" and HTTP 429. The StatusCode, Message, and EmitRetryAfter are overridable through ApiPilotRateLimitOptions.


Browser client

@apipilot/client is a zero-runtime-dependency browser fetch client. It speaks the same wire contract as the server.

import { createApiPilotClient } from '@apipilot/client';

const client = createApiPilotClient({
    baseUrl: 'https://api.example.com',
    // C1-C7 overrides (all optional except baseUrl):
    csrfPath:         'csrf',
    credentials:      'same-origin',
    protectedMethods: ['POST', 'PUT', 'PATCH', 'DELETE'],
    csrfHeader:       'X-CSRF-TOKEN',
    onCsrfExpired:    (err) => console.warn('CSRF token expired', err),
    // fetch: myCustomFetch,
});

const response = await client.get('/api/orders/1');
console.log(response.data);

await client.post('/api/orders', { item: 'widget' });

The client holds the CSRF token in memory only - never in localStorage or sessionStorage. It attaches the CSRF header only to protected methods on the configured origin.


Samples

Two standalone samples, both outside the solution, both zero-dependency.

Samples.Api - the reference API

A single-host reference API exercising the full surface.

dotnet run --project dotnet/samples/Samples.Api/Samples.Api.csproj

Endpoints: GET /api/ok, GET /api/fail, POST /api/validate, GET /api/items, GET /api/csrf, POST /api/submit, GET /api/limited. See dotnet/samples/Samples.Api/README.md for run commands and how to exercise the CSRF and rate-limit paths.

Samples.MultiInstance - shared Data Protection key ring

Two ApiPilot instances sharing a persisted key ring and application name. A CSRF token issued by instance A validates on instance B. The two requirements: a shared persisted key ring and a shared application name.

dotnet run --project dotnet/samples/Samples.MultiInstance/Samples.MultiInstance.csproj

See dotnet/samples/Samples.MultiInstance/README.md.


Evidence and quality

Every number below is counted from an actual run at the v1.0.0 close.

Gate Result
Solution build (9 projects) succeeded, 0 warnings, 0 errors
Core tests 23 classes / 219 tests passed
AspNetCore tests 52 classes / 377 tests passed
Security tests 41 classes / 347 tests passed
Contract tests 3 classes / 15 tests passed
Fuzz tests 5 classes / 27 tests passed
Browser tests 1 class / 6 tests passed / 1 fixture Unavailable (by design)
.NET total 125 classes / 991 executed tests / 1 Unavailable
JavaScript tests 5 files / 60 tests passed
Audit PASS (Sections 1-9, zero failures, zero warnings)
SBOM generated per release (SPDX 2.3); attached to the release artifacts
Packages packed 3 nupkg at 1.0.0
Release workflow tag-triggered via .github/workflows/release.yml
Independent security review Not yet scheduled

The browser suite drives a real headless Chrome/Edge over the Chrome DevTools Protocol - no browser automation package is bundled. One fixture (the HTTPS reverse-proxy scenario) is recorded as Unavailable by design; it is never reported as a passing security assertion.

Run the entire suite:

$repo = 'C:\Users\HP\Desktop\ApiPilot'
& dotnet build "$repo\dotnet\ApiPilot.slnx" -c Release --nologo

foreach ($p in @('ApiPilot.Core.Tests','ApiPilot.AspNetCore.Tests','ApiPilot.Security.Tests',
                 'ApiPilot.ContractTests','ApiPilot.FuzzTests')) {
    & dotnet run --project "$repo\dotnet\tests\$p\$p.csproj" -c Release --no-build
}

& dotnet run --project "$repo\dotnet\tests\ApiPilot.BrowserTests\ApiPilot.BrowserTests.csproj" `
    -c Release --no-build -- --allow-skip

Push-Location "$repo\javascript\ApiPilot.Client"
& node --test --test-reporter=tap "tests/**/*.test.js"
Pop-Location

& powershell -NoProfile -ExecutionPolicy Bypass -File "$repo\audit.ps1"

Design principles

  • Zero third-party runtime dependencies. The library builds on the .NET 10 SDK, the .NET BCL, and the ASP.NET Core framework. The test harness is repository-local; the browser suite uses the Chrome DevTools Protocol directly. audit.ps1 enforces the boundary.
  • The API contract is frontend-agnostic. HTTP + JSON + cookies + headers is the interoperability boundary. React, Vue, Angular, Svelte, Blazor, vanilla JS, mobile clients, and any HTTP consumer use the same contract.
  • The authentication credential is never exposed to JavaScript to simplify frontend integration. CSRF uses a separate request token.
  • The core package is framework-independent. ASP.NET Core integration and the security surfaces live in separate packages.
  • Every transformation has a sensible default and a first-class override. Query-parameter names, sort syntax, page numbering, HTTP success status, correlation header, correlation ID format - all overridable through options or delegates without forking the library.
  • Fail-closed security. An insecure configuration prevents the host from starting. There is no silent fallback to a default.
  • Published versions are immutable. Any change, including documentation, gets a new version number.

Roadmap and limitations

Shipped in 1.0.0

The full boundary: envelope, error contract, validation, pagination, filtering and sorting, correlation, serialization, content negotiation, CSRF, cookies, Origin, Fetch Metadata, Data Protection, observability, rate-limit integration, multi-instance, OpenAPI, supply-chain artifacts, and the browser client.

Post-1.0.0 backfills

  • B.5 - consolidate two same-name ApiPilot Meter instances.
  • B.7 - derive the version from the assembly instead of hard-coding it in three diagnostics constants.
  • B.8 - correct the audit Section 9 output label.

Planned (optional)

  • 6.0 - additional framework examples.
  • 6.1 - enterprise deployment enhancements.
  • 6.2 - v2.0 synchronizer-token CSRF mode (optional).
  • 6.3 - v2.1 sensitive-action token (optional).
  • 6.4 - additional language roots (Python, Go) - structure only.

Not included by design

Retry, circuit breaker, idempotency, payment processing, authentication, authorization, JWT issuing, business logic, database access, and caching. These belong to the application or to a companion resilience library.


Project status - honest notes

  • Published on NuGet. The three packages are live at nuget.org; see Releases for the current version.
  • No external production consumer yet. The sample and the test suite are the evidence. A case study will be added when one exists.
  • No independent security review scheduled. The internal test suites (contract tests, fuzz tests, the browser security suite) have passed; no external reviewer has been engaged.
  • Package signing is not yet enabled. The release workflow is fail-closed: it skips Authenticode signing when no certificate is configured and publishes with a NuGet repository signature. Adding a certificate is a one-secret change with no workflow edit.

Contributing

ApiPilot is an open-source project. Contributions are welcome.

Reporting a bug or requesting a feature:

Submitting a change:

  • One concern per PR. Keep each pull request focused.
  • Tests for every change. Every new behavior needs a test; every fixed defect needs a regression test.
  • Docs updated in the same PR. If the change affects the contract, update the relevant file under docs/ and SPEC.md in the same commit.
  • Zero build warnings. The repository enforces TreatWarningsAsErrors=true. A PR that introduces a warning will not build.
  • audit.ps1 must pass. The audit enforces the boundary rules and the zero third-party dependency policy. A PR that introduces a forbidden symbol or a third-party production package reference fails the audit and will not be merged.
  • CI must be green. Every push and pull request runs the full test suite (six .NET harnesses plus the JavaScript client) on GitHub Actions.

Before submitting a change, run audit.ps1 locally and confirm CI passes on your branch.


License

ApiPilot is licensed under the MIT License. See LICENSE.


Author

Alexander Sanchez Cyril (@sancy1)

ApiPilot was built as a standalone API boundary library, extracted from the author's portfolio of .NET services. It is the companion library to Portfolio.Resilience - the two compose at different layers:

  • Portfolio.Resilience owns how an application safely executes an external or transiently unreliable operation.
  • ApiPilot owns what the API sends back after the application has produced a result or a terminal failure.

For a production case study of the resilience companion, see File-Ferry

  • a Windows desktop application that uses Portfolio.Resilience for every filesystem operation.

The full history - every change and every finding, with sequential IDs - is in CHANGELOG.md.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on ApiPilot.AspNetCore:

Package Downloads
ApiPilot.Security

CSRF protection, secure cookie profiles, Origin policy, and Fetch Metadata for ApiPilot. Requires ApiPilot.Core and ApiPilot.AspNetCore. See the full boundary at https://github.com/sancy1/ApiPilot.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.6 127 10/1/2026
1.0.5 111 9/30/2026
1.0.4 103 9/30/2026
1.0.3 106 9/29/2026
1.0.1 110 9/29/2026
1.0.0 123 9/29/2026