Skip to content
Clean GraphQL 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:7331, and on http://localhost:7330, 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
/graphql The endpoint. POST a query, or open it in a browser for Nitro
/graphql?sdl The schema in SDL, the same text the snapshot test checks
/health/live Answers 200 while the process is up
/health/ready Answers 200 when the database can be reached
http://localhost:7332 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:7332. Open Traces to follow a request from the HTTP request through the GraphQL operation 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 7333 and 7334. 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:7333 dotnet run --project ./src/Presentation

Nitro is the easy way: it knows the schema, autocompletes, and keeps your query history. The sample data uses a fixed seed, so these ids are the same on every machine. See the schema reference for every query, mutation and type.

# One movie, its reviews and who wrote them
{
movie(id: "cb188ef6-14e7-f85f-2f78-924c2ab26b28") {
title
reviews { stars text author { firstName lastName } }
}
}
# Write a review
mutation {
createReview(input: { authorId: "01fa8b58-05d2-abd4-e55c-2633222dd0a5", movieId: "cb188ef6-14e7-f85f-2f78-924c2ab26b28", stars: 5, text: "Great film. I cried at the ending." }) {
review { id stars text }
errors { __typename ... on Error { message } }
}
}
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

The version query then reports 1.2.3-beta and the commit it was built from.