Skip to content
Clean Web API
Lean Mean Clean Apps

Five templates, one brand, one search box. Everything in the docs is in here, including the bits we hoped you'd skim.

Try one of these

Results say which template they came from, so you won't end up reading about Lambda when you wanted GraphQL. Again.

Run it locally

There are two ready-made environments. local is for dotnet run: sample data on, logs to the console. docker is for Docker Compose: sample data on, logs, traces and metrics to the Aspire dashboard, database on a volume. Both are for your machine. Neither is for production, which is why neither is the default.

Terminal window
dotnet run --project ./src/Presentation

launchSettings.json sets the environment to local and listens on https://localhost:7341, and on http://localhost:7340, which redirects to it. If your browser or curl doesn’t trust the .NET development certificate yet, run dotnet dev-certs https --trust once.

Where What
/scalar The Scalar API reference, built from the OpenAPI document
/openapi/v1.json The OpenAPI document itself
/health/live Answers 200 while the process is up
/health/ready Answers 200 when the database can be reached
/api/version The version stamped into the build. Needs a token when authentication is on
http://localhost:7342 The Aspire dashboard, with the logs, traces and metrics, when running with Docker Compose

The health endpoints answer without a token even when authentication is on, so a load balancer never needs to log in.

Docker Compose runs an OpenTelemetry Collector beside the API, and the collector forwards everything to the Aspire dashboard at http://localhost:7342. Open Traces to follow a request from the HTTP request to the use case, Structured for the logs, each linked to its trace, and Metrics for request durations, EF Core queries and the runtime. The dashboard keeps everything in memory, so it’s empty again after a restart. The dashboard has no login, and the collector accepts OTLP from anyone on ports 7343 and 7344. That’s on purpose, so there’s nothing to sign in to on your machine, and it’s why the compose file is for your machine only. Don’t run it anywhere other people can reach.

The API only ever talks OTLP to the collector, and otel-collector.yaml decides where things go. To send them to a real backend, add its exporter there; the API doesn’t change. To see a dotnet run in the dashboard, start the collector and point the API at it:

Terminal window
docker compose up -d otel-collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7343 dotnet run --project ./src/Presentation

Open src/Presentation/Presentation.http in Visual Studio, Rider or VS Code to run a request for every endpoint in one click, or call them from the terminal. These use the dotnet run address; with Docker Compose, use http://localhost:7340 instead. The sample data uses a fixed seed, so these ids are the same on every machine. See the endpoint reference for every parameter and response.

Terminal window
# Search movies, two at a time
curl "https://localhost:7341/api/movies?query=space&limit=2"
# One movie, with its reviews
curl "https://localhost:7341/api/movies/cb188ef6-14e7-f85f-2f78-924c2ab26b28"
# Write a review
curl -X POST "https://localhost:7341/api/reviews" -H "Content-Type: application/json" \
-d '{"authorId":"01fa8b58-05d2-abd4-e55c-2633222dd0a5","movieId":"cb188ef6-14e7-f85f-2f78-924c2ab26b28","stars":5,"text":"Great film. I cried at the ending."}'
Terminal window
dotnet test

The tests build their own in-memory SQLite databases from the same migrations and seed, so nothing touches movie-reviews.db. Test your changes covers where a test goes, how the tests are written and how to check coverage before CI does.

The Dockerfile has a stage for each job, so you can build only what you need.

Stage What it does
build Restores and builds the solution
test Runs every test with coverage, and saves the result instead of failing the build
results Exports the test results, the coverage report and the exit code to your machine
publish Publishes the Presentation project
run The image you deploy
Terminal window
docker build . --target results --output type=local,dest=out

A failing test doesn’t fail the build, so the results still come out. Check out/exit-code: anything other than 0 means a test failed, and a pipeline built on these stages should fail on it.

Terminal window
docker build . --target run --tag worksonmymachine-movies:latest \
--build-arg VERSION_PREFIX=1.2.3 --build-arg VERSION_SUFFIX=beta

GET /api/version then reports 1.2.3-beta and the commit it was built from.