On this page
Create your first API
Run a real .NET HTTP service with invariant JSON, structured logs, OpenAPI and Scalar.
Build a small .NET 10 HTTP service with invariant technical JSON, structured logs and an OpenAPI document. This tutorial uses the published 0.19.0 packages. It needs no database, identity provider, collector or frontend.
Before you start
Install a .NET 10 SDK and complete NuGet feed configuration. Keep the package-read credential in your credential provider or runtime environment. The source repository is not required: the application references NuGet packages.
Create the application
dotnet new web --framework net10.0 --name FirstApi
dotnet add FirstApi package Fabricators.Kernel.AspNetCore --version 0.19.0
dotnet add FirstApi package Fabricators.OpenApi --version 0.19.0
dotnet add FirstApi package Fabricators.Observability --version 0.19.0Replace FirstApi/Program.cs with this complete program:
using Fabricators.Kernel.AspNetCore;
using Fabricators.Kernel.Common;
using Fabricators.Observability;
using Fabricators.OpenApi;
using Microsoft.AspNetCore.Builder;
FoundationRuntime.UseInvariantCulture();
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundationRuntimeDefaults();
builder.Services.AddFoundationOpenApi("First Foundation API");
builder.AddFoundationObservability(options =>
{
options.ServiceName = "first-api";
options.ServiceVersion = "1.0.0";
});
await using var app = builder.Build();
app.MapGet("/hello", () => new
{
service = "first-api",
amount = 1234.56m,
timestamp = TimeProvider.System.GetUtcNow(),
});
app.MapFoundationOpenApi();
await app.RunAsync();The process opts into invariant culture before creating the host. Runtime JSON requires numeric JSON values and offset-qualified timestamps; display preferences are a separate concern. The log service name identifies this application, while the package version identifies its Foundation dependency.
Run and exercise it
dotnet run --project FirstApi --no-launch-profile -- --urls http://localhost:5200 --environment DevelopmentOpen /hello at http://localhost:5200, or request it with your HTTP client.
The response contains service: "first-api", the JSON number 1234.56 and a current
offset-qualified timestamp. The timestamp varies; punctuation and decimal parsing
do not depend on the workstation's locale.
Open /openapi/v1.json for the machine-readable schema and /scalar for the API
reference UI. The document includes GET /hello. Look at the application's console:
logs are structured JSON with the configured service identity.
This exact source is compiled as an independent package consumer and exercised through real HTTP, including JSON, OpenAPI and Scalar, by the verification runner. It is a public demonstration endpoint, not an authentication or tenant model.
Understand the production difference
Stop the process and run with --environment Production. /hello still works;
OpenAPI and Scalar are not exposed without an explicit authorization policy. This
is the default disclosure boundary, not a missing deployment asset. Protect the
schema and UI with the same product policy when enabling them in production.
The example sends no telemetry to an external collector. Configure a trusted OTLP endpoint when ready; see observability. Do not enable response measurements just to confirm that logs work: those have their own permission/environment gate.
Add one capability at a time
| Your next requirement | Continue with |
|---|---|
| Browser, PWA or Capacitor sign-in | Choose the authentication path |
| Client locale and timezone | Runtime defaults and presentation |
| SMTP or Microsoft 365 delivery | Configure outgoing email |
| Several modules sharing an EF model | Compose persistence |
| Cached read models | Cache safely |
Keep package ownership nearby: adding an adapter does not create users, tables, permissions, background jobs or business workflows.