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.
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 GitHubIt 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.
What the build refuses.
Two classes of API bug that usually show up in production become build errors.
$ dotnet build
Program.cs: error BRAMA001: No HTTP status code is mapped for ErrorKind.Unauthorized.
Add .Map(ErrorKind.Unauthorized, …) to this ProblemDetails configuration.$ 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.
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.
obj/, and the MSBuild target diffs and promotes it.dotnet build, locally and in CI alike. A test asserts that a design-time build never touches the committed contract.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 ↗
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.
What it doesn’t do.
Stated up front, because a tool that claims safety has to be clear about where that safety ends.
Contracts check structure only: routes, request and response shapes, and status mappings. They can't see a change in behaviour.
Making a request field required breaks clients, but it shows up as an addition, because required-ness isn't recorded in the contract yet.
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.
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.