menu

Adding OpenAPI Support to Mummy, a Nim HTTP Framework

●1 ●4
calendar_today ago • schedule3 min read
— Originally published at dev.to

Adding OpenAPI Support to Mummy: Lessons from Extending Nim's Thread-Per-Request HTTP Server

Mummy is a multi-threaded HTTP 1.1 and WebSocket server for Nim built around a simple, unapologetic idea: skip async/await entirely and let a pool of worker threads handle requests the old-fashioned way — one thread, one request, blocking calls allowed. No Future[T], no colored functions, no async stack traces to untangle. For a systems language with real threads and ARC/ORC to make that cheap, it's a compelling trade.

What Mummy doesn't ship with, though, is any notion of API documentation. There's no built-in way to describe your routes, generate a schema, or hand a frontend team (or your future self) a /docs page. That gap is what got me building.

Why This Gap Matters

Nim's web ecosystem is small enough that most frameworks are optimized for the author's own use case first. Mummy is optimized for raw throughput and simplicity — and it succeeds at both. But once an API has more than a couple of routes, "read the source to find out what a request body looks like" stops scaling. OpenAPI (formerly Swagger) solves this by generating a machine-readable schema of your API directly from your code, which then powers interactive docs, client SDK generation, and request validation.

I forked Mummy and built this in as a layer on top, rather than a separate tool that has to be kept in sync by hand.

What I Built

The fork adds two core modules — openapi_schema.nim and openapi_router.nim — plus an OpenApiRouter that wraps Mummy's normal routing with metadata: summaries, tags, and response schemas generated via schemaOf. Every one of the 12 bundled examples now serves a live /openapi.json and an interactive /docs page, generated from the same route definitions that handle requests — no separate spec file to maintain.

From there I added three more pieces that came up naturally once the schema layer existed:

  • Typed path params (openapi_params.nim) — pathParam[T](request, "id") pulls a path segment straight out as an int, string, or whatever type you declare, instead of manually parsing strings on every handler.
  • Request body validation (openapi_validation.nim) — parseValidatedBody[T] checks an incoming JSON body against the same schema that schemaOf generated for your docs, so the validation and the documentation can't drift apart.
  • Composable middleware (openapi_middleware.nim) — a Middleware type and a use() method on the router, with logging and bearer-auth middleware included out of the box.

Every feature was compiled and exercised with real HTTP requests, not just nim check, before I called it done — including converting a wildcard WebSocket route to a named path param and confirming it fixed a small latent bug where the old code read the raw request URI (query string and all) instead of the decoded path.

What the Wider Nim Community's Experience With Mummy Adds

Reading through discussion around Mummy on the Nim mailing list and forum was useful context while building this. One recurring theme: Mummy's design intentionally keeps some things out of scope in the name of simplicity. A developer comparing thread-per-request servers noted that Mummy's multipart handling, while present, buffers the entire upload into memory rather than streaming it — a deliberate trade-off for simplicity that matters if you're building something like a file-upload service, and pointed to alternatives like Guildenstern for cases needing streaming multipart support.

That trade-off is directly relevant to schema-driven validation work: parseValidatedBody[T] inherits the same "load it all, then check it" model. For typical JSON APIs that's a non-issue, but it's a useful thing to know going in if you're planning a Mummy-based service that also needs large file uploads — you may want to keep that path outside the validated-body flow rather than fight the framework's grain.

It's also worth knowing you're not alone in wanting typed, schema-aware APIs on Mummy — a separate project, Sarcophagus, tackles a similar problem from a different angle: typed request/response encoding across JSON, CBOR, and MessagePack, plus its own Swagger/OpenAPI generation and OAuth2 helpers. Different design choices, same underlying itch in the ecosystem — which suggests this is a real gap worth filling rather than a one-off preference of mine.

Putting It to Use

To validate the fork beyond the bundled examples, I built a small Todo API demo using the typed params, validation, and middleware together, and I'm deploying it live on Render as a working reference — a REST API with real request validation and generated docs, running on a threaded model with no async in sight.

Where This Goes Next

The fork is usable today for anyone building JSON APIs on Mummy who wants documentation and validation that can't silently drift from the actual routes. If you're working in the Nim web space and hit the same "no schema, no docs" wall, I'd genuinely like to hear how you're solving it — feel free to reach out.

4 Comments

•

You asked how other people are solving this, so here is where I would press on the design, because generating the spec turns out not to be the hard part.

Deriving the docs and the validator from the same schemaOf call removes drift between the doc and the validator. It does not remove drift between either of them and what the handler actually does. Request bodies get parseValidatedBody[T]. Responses get documented and then trusted. That asymmetry is where most of the breakage I have seen in long-lived APIs lives, usually a handler that quietly adds a field the response schema never declared, or an error shape that appears nowhere in /openapi.json. In a compiled language you can close it cheaply: validate responses against the generated schema behind a compile time flag that is on in test and dev and off in release, so CI catches the mismatch and production pays nothing for the check.

The error shapes are the ones I would do first. When parseValidatedBody[T] rejects a body it produces some response, and if that shape is not in the spec then every generated client SDK handles only the happy path. Having 12 examples already serving a live spec puts you in a good position to fix that once at the router layer instead of per handler.

On the multipart trade-off you mention, I think it bites harder on thread per request than the framing suggests. On an async server a request blocked reading a large body is a suspended future and costs almost nothing. On Mummy it is a worker, and workers are a fixed pool, so a handful of slow or oversized bodies pin the pool and everything behind them queues with no signal that anything is wrong. That argues for a hard body size limit enforced by the router before parse rather than inside the validator, and for that limit appearing in the generated spec so callers learn it from the doc rather than from a timeout.

Last one, and it is why I would not file any of this under documentation polish. A lot of what reads an OpenAPI document now is an agent, and an agent treats the spec as the whole world. A person hitting an incomplete spec opens your source. An agent does not, and it retries. So whether POST /todos is safe to replay stops being a nicety and becomes the difference between one todo and two, and OpenAPI has no native field that says it. A description convention or a vendor extension is not elegant, but it beats the caller guessing.

2 votes
•

@[Mike Dabydeen], this is exactly the kind of pushback I was hoping for — thanks for the depth.

On response validation: you're right that I only closed half the loop. Validating responses against the same schemaOf output behind a compile-time flag (on in test/dev, off in release) is the right shape — it catches drift in CI without a runtime cost in production, and it fits Mummy's model since there's no async boundary to complicate where the check happens. I'll wire that into the router layer next.

On error shapes: agreed, and this is the easier fix of the two. parseValidatedBody[T] currently raises a rejection with an ad hoc shape per handler. Standardizing that into a single documented error schema registered once at the OpenApiRouter level (rather than per handler) means all 12 examples — and anything built on the fork — gets a spec-accurate error response for free. Doing it there instead of per-handler was the right call to flag.

On the multipart/body-size point — you've identified something I underweighted. I was thinking about the memory cost of buffering the whole body, not the pool-exhaustion angle. On an async server a slow body is a parked future; on Mummy it's an occupied worker out of a fixed pool, so a few oversized or slow requests can back up everything behind them with no visible error. A hard size limit enforced by the router before parsing (not inside the validator) is the right layer, and surfacing that limit in the generated spec means callers find out from the docs instead of a timeout. I'll add that as a router-level option.

On the agent point — that's the one I hadn't considered at all. A human hitting a thin spec reads the source; an agent replays. OpenAPI has no native idempotency/safety field, so I'd rather lean on a vendor extension (something like x-idempotent or x-safe-to-retry per operation) than a description convention, since a convention is exactly the kind of thing an agent won't reliably parse but a structured field will. Worth adding to the schema generation so it shows up in /openapi.json rather than being tribal knowledge.

Appreciate you taking the time to write this out — going to work all four of these into the next round of changes on the fork.

1
•

@[peter isaiah] Vendor extension over description convention is the right call, and there are two things worth knowing before you settle on the name.

There is no standard field to align with, and it is not for lack of trying. The IETF httpapi working group has a draft for an Idempotency-Key request header that reached revision 07 and then expired without ever becoming an RFC. So you are not choosing between your extension and a blessed alternative. You are choosing inside a gap that has stayed open for years, which means whatever you pick is as defensible as anything else on offer, and also that nothing downstream will recognize it on your behalf.

Which is the practical catch with x- extensions: most generators drop unknown ones. If the agent reads /openapi.json directly you are fine. If somebody generates a client from your spec and the agent calls that, the field is gone at exactly the layer where retry behavior lives. Worth one line in the docs saying the property travels with the raw spec only, because that failure is silent and it looks like the field never mattered.

The other thing I would separate is that safe to retry and safe to retry how are two different facts, and an agent needs both. A boolean says the operation can be replayed. It does not say replayed within what window, or keyed on what, and those change the answer. Something idempotent for 24 hours keyed on a caller supplied header is a different contract from something naturally idempotent forever, and an agent that treats them as the same field will get the second one right and the first one wrong at hour 25. Since you are adding a field anyway, a small object costs you nothing now and saves you a migration later.

0
•

@[Mike Dabydeen] I will surely put that in mind when implementing the next phase.
I hope to use the next phase in my already existing job crawler. Thank you for the brilliant insight.
Do you mind sharing what you are currently working on.

0
🔥 Join developers growing publicly
Share your knowledge, build in public, and grow your developer presence with a global community.
Join CoderLegion

More Posts

Running OpenAPI Validation in GitHub Actions and Showing Findings in Pull Requests

Ganesh Kumar - Jul 3

How to Build a Portfolio Website That Actually Gets You Hired

muhammadfarhan.dev - Aug 21

Merancang Backend Bisnis ISP: API Pelanggan, Paket Internet, Invoice, dan Tiket Support

Masbadar - Mar 13

I’m a Senior Dev and I’ve Forgotten How to Think Without a Prompt

Karol Modelski - Mar 19

Everyone says DeepSeek is cheaper, but I got tired of guessing the exact math. So I built a calculat

abarth23 - Apr 27
chevron_left
Isaiah Peter
145 Points • 5 Badges
Lagos, Nigeria • isaiah.name.ng
1Posts
2Comments
1Connections
Nim & AI engineer in Lagos, Nigeria. Building backend systems, extending the mummy HTTP framework with OpenAPI tooling.

Related Jobs

View all jobs →

Commenters (This Week)

1 comment
1 comment

Contribute meaningful comments to climb the leaderboard and earn badges!