cat brama/README.md

Brama

A library for REST APIs on ASP.NET Core minimal APIs. It catches API mistakes during dotnet build, using a Roslyn source generator and an MSBuild step: an error type with no HTTP status, or a breaking change to a version that has already shipped. It sits on top of ASP.NET Core routing rather than replacing it.

.NET 10RoslynSource GeneratorsMSBuildMinimal APIs

Status Proof of concept. Not on NuGet. The API will likely change, and if Brama doesn’t meet the needs it was built for, it will be archived.

View source on GitHub
grep -r bugs lanka/src/Api

It started with an audit of my own code.

Before designing anything, I went through the API layer of Lanka, my diploma project. Every core decision in Brama traces back to something I found there.

500 for 401
The ErrorKind → HTTP status switch had no Unauthorized case, so about 17 handlers answered 500, with a problem body that contradicted itself: a 401 type, a 500 status. Brama makes a missing mapping a build error.
3 error paths
Handler results, a global exception handler, and raw empty-body 401/403 from the auth middleware each produced a different response shape. Brama sends all of them through one problem+json table.
Leaked detail
The exception handler put exception.Message into responses in every environment. In Brama, exception detail is hidden unless a callback explicitly opts in.
Boilerplate
The same Result.Match dispatch on almost every one of ~73 endpoints, and a ~25-line DI registration block hand-copied across 4 modules. Brama converts results itself and generates the DI registration.
dotnet build

What the build refuses.

Two classes of API bug that usually show up in production become build errors.

An error kind with no HTTP status
$ dotnet build
Program.cs: error BRAMA001: No HTTP status code is mapped for ErrorKind.Unauthorized.
Add .Map(ErrorKind.Unauthorized, …) to this ProblemDetails configuration.
A breaking change to a shipped version
$ dotnet build
error BRAMA010: Orders.v1 has already shipped, and this build removes 1 thing(s) from its contract:
  - response.field  GET /orders/{id:guid}  Status : string
Add .AcceptBreakingChange(reason: "...") to that group if the break is intended, or restore the surface.

The first real build of a versioned group writes its contract to contracts/Orders.v1.contract.txt, which you commit. The format is one sorted fact per line, so the rule is exact: a change is breaking if any committed line is missing from the new build. Adding endpoints or fields isn’t a break. An intended break is declared in C# with a reason, so it shows up in the same pull request as the code that causes it.

cat docs/design.md#contracts

The decision that shaped it.

The source generator computes the contract, but it never writes the committed file. A separate MSBuild step does that, and only on a real build.

Why
A generator runs on every keystroke in the IDE. If it wrote the tracked contract, a breaking change would be accepted into the snapshot the moment you typed it, before any real build had checked it. So the generator only emits a model under obj/, and the MSBuild target diffs and promotes it.
Payoff
The snapshot can’t be rewritten mid-edit, and there’s no separate CLI to install. The check runs inside dotnet build, locally and in CI alike. A test asserts that a design-time build never touches the committed contract.
Cost
Two moving parts instead of one, plus a hard constraint: the configuration has to be readable from source. Anything the generator can’t follow is reported as BRAMA011 instead of being skipped, because looking enforced without being enforced is worse than not checking at all.

The design document also compares Brama with FastEndpoints, Asp.Versioning, Pact and others, so that it adds what they don’t rather than re-wrapping them. Read the design in full ↗

ls src/ --why

How the pieces fit.

Config tree

Settings are declared once on the API, a group, or an endpoint, and inherited downward. List settings such as filters append root-first, single values override, and Replace clears an inherited setting for one subtree only.

Errors

ErrorKind is a closed enum, so the full set of mappings is known at compile time. Validation failures, filters that short-circuit, authorization failures and unhandled exceptions all come out as RFC 9457 problem+json.

DI modules

A [Module] class gets a generated AddXModule() with every registration written out literally. No assembly scanning or reflection runs at startup.

Links

Naming an endpoint generates a typed Links.<Name>(…) method, so link parameters are checked by the compiler, and the version prefix comes from routing instead of a hand-built string.

Opt-in extras

URL-segment versioning, correlation IDs, request logging per group, rate-limit headers, Deprecation and Sunset headers, per-endpoint CORS, and output caching. Each one is off until a node in the tree turns it on.

102 tests cover it. They include end-to-end MSBuild tests that run real dotnet build processes against a throwaway project, to prove the contract step freezes, fails and accepts changes the way it claims.

cat KNOWN_LIMITS

What it doesn’t do.

Stated up front, because a tool that claims safety has to be clear about where that safety ends.

01

Contracts check structure only: routes, request and response shapes, and status mappings. They can't see a change in behaviour.

02

Making a request field required breaks clients, but it shows up as an addition, because required-ness isn't recorded in the contract yet.

03

The build-time checks read source code, so configuration built in a loop or passed to another method can't be followed. Brama says so with BRAMA011 instead of skipping the check silently.

04

Out of scope by design: non-JSON content, PATCH, ETags, idempotency keys, and outbound HTTP. Each one would reopen a decision the design has already made.

Get in touch

Open to mid-level backend .NET roles in Sweden, or elsewhere in the EU with relocation. Email is the fastest way to reach me.

Elsewhere
LinkedIn, or view my CV
Work rights
I’m authorized to work in Sweden. Anywhere else in the EU, I would need a work permit.