# 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](/foundation/0.19.0/guides/getting-started/#configure-package-sources).
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](/foundation/0.19.0/guides/observability/). Do not enable response
measurements just to confirm that logs work: those have their own
[permission/environment gate](/foundation/0.19.0/guides/authorization/).

## Add one capability at a time

| Your next requirement | Continue with |
| --- | --- |
| Browser, PWA or Capacitor sign-in | [Choose the authentication path](/foundation/0.19.0/guides/authentication-paths/) |
| Client locale and timezone | [Runtime defaults](/foundation/0.19.0/guides/runtime-defaults/) and [presentation](/foundation/0.19.0/guides/presentation-localization/) |
| SMTP or Microsoft 365 delivery | [Configure outgoing email](/foundation/0.19.0/guides/mail-setup/) |
| Several modules sharing an EF model | [Compose persistence](/foundation/0.19.0/guides/module-persistence/) |
| Cached read models | [Cache safely](/foundation/0.19.0/guides/caching/) |

Keep [package ownership](/foundation/0.19.0/guides/packages/) nearby: adding an adapter does not create
users, tables, permissions, background jobs or business workflows.
