https://theflyingcoders.dev/tags/api-design/Recent content in Api Design on theflyingcodersHugoen-gbTue, 27 Oct 2026 09:00:00 +0000https://theflyingcoders.dev/blog/spec-driven-development-openapi/Tue, 27 Oct 2026 09:00:00 +0000https://theflyingcoders.dev/blog/spec-driven-development-openapi/<p>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.</p>https://theflyingcoders.dev/blog/rest-error-taxonomy/Tue, 13 Oct 2026 09:00:00 +0100https://theflyingcoders.dev/blog/rest-error-taxonomy/<p>If your API can return an error in fifty different JSON shapes, your clients handle none of them and everyone ends up parsing a <code>message</code> 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 <a href="https://theflyingcoders.dev/blog/behaviour-driven-error-handling-lathos/">lathos post from last time</a>.</p>