Writing · Tag
api design
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