Skip to content
fabricators docs
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

Text
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.0

Replace FirstApi/Program.cs with this complete program:

csharp
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

Text
dotnet run --project FirstApi --no-launch-profile -- --urls http://localhost:5200 --environment Development

Open /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.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0