Writing · Category
Code structure & architecture
Posts
Spec-driven development: the OpenAPI file is the source of truth
Code structure & architectureOct 27, 20265 min
When I start a new service, I do not write the HTTP handlers by hand. I describe the API in an OpenAPI file first, and the handlers are generated from it. The compiler then will not let the spec and the code drift apart: you change the spec, run one command, and the build stays broken until the handlers match. I would not build a JSON API any other way now, and the reason is the mess it replaced.
Read the post
A REST error taxonomy: frozen codes and three shapes
Code structure & architectureOct 13, 20264 min
If your API can return an error in fifty different JSON shapes, your clients handle none of them and everyone ends up parsing a message string with a regex. So pick a small fixed set of shapes, give every error a stable code, and never let an endpoint invent its own. This is the taxonomy I put on every API, and it is the other half of the lathos post from last time.
Read the post
Behaviour-driven error handling: lathos and one global handler
Code structure & architectureSep 29, 20264 min
An error is a not-found because it says it is, not because of what type it happens to be. That one idea is what lets me delete the pile of errors.Is blocks out of every handler and put the whole HTTP-status decision in a single place. Here is how it hangs together, with the library I use for it, lathos.
Read the post
How this blog is built and hosted for nothing
Code structure & architectureSep 14, 20264 min
This site has no server and costs nothing to run. Here is the whole stack, why every piece is the boring choice on purpose, and how fast I can stand one up for you.
Read the post
How I lay out a Go repo: three layers, one direction
Code structure & architectureSep 12, 20266 min
Domain imports nothing and internal owns the logic. Transports hold none of it, whether that is an HTTP handler or a queue consumer, and the data layer swaps under the service without a handler noticing.
Read the post