api-design
Response shapes, error models and contracts a client can rely on.
-
Turning Alertmanager Webhooks Into Retained MQTT State
Alertmanager's webhook delivers an event to whoever happens to be listening at the moment it fires, which is no help to a system that connects later and wants to know what is currently active. This builds a small bridge that keeps current alert state in Redis and republishes it to MQTT as retained messages, with a complete setup that runs on a laptop.
-
OIDC Client Shapes: A Token-Validating API Is Not a Login Client
Configuring every OIDC client the same way conflates "users log in here" with "this service validates a token", and the wrong shape accepts flows nobody intended. This article covers the three client shapes and gives working Keycloak configuration plus a Python JWT validator that checks issuer, audience and signature.
-
Separating 'Cannot Ever' From 'Currently Broken' in Sweep Automation
A sweep that checks a list of targets for a feature has to decide what a failure means, and a response code alone cannot tell it whether that failure was expected or is a regression. Here is how to make that decision explicit, keep it loud when it should be, and test it so the escape hatch does not become a second way to hide problems.
-
Designing a Docker Image Build API: Job Model and Streamed Logs
An HTTP endpoint that triggers a Docker image build cannot behave like a normal request/response call, because the build takes an unpredictable amount of time and a client needs to watch its output as it happens rather than poll for a final result. This article designs the job and streaming model for that, with a complete Go service built on the Docker SDK.
-
A 500 That Was a Misconfigured Client, Not an Auth Failure
Code that assumes an OAuth2 introspection response always carries an active field works right up until the resource server's own client credentials are wrong, at which point every request that reaches it throws instead of returning a clean 401. This article separates the response shapes introspection can actually return and gives a tested client that handles all of them.
-
An OpenAI-Compatible Proxy in Front of a Local Model Server
Local model servers speak a shape close enough to the OpenAI API that existing SDKs and tools can point at them unmodified, but close enough is not the same as safe to expose. This builds a small FastAPI proxy that adds authentication and a health check that cannot itself trigger a model load.
-
One Dashboard on Five Unrelated Backends: Normalising at the Boundary
A dashboard that calls a ticketing system and a CI system directly inherits their different pagination styles, error shapes and auth schemes. This article builds a FastAPI backend-for-frontend that normalises both into one schema, degrades gracefully when an upstream is down, and shows how to test each adapter without touching a real upstream.
-
Idempotent Payment Webhooks with a Deduplication Table
Payment providers deliver webhooks at least once and retry on anything but a 2xx response, so a handler that is not explicitly idempotent will eventually process the same payment twice. This covers signature verification, a deduplication table with a unique constraint, and a transactional handler that makes redelivery a no-op, with a complete example and a test that proves it.
-
Modelling an Order Lifecycle as an Explicit State Machine
When any code path can set order.status to any value, an invalid transition is caught only by whoever remembers to check for it, and eventually nobody does. This walks through modelling the lifecycle as an explicit state machine that rejects illegal transitions by construction, with a complete, tested implementation.
-
Managing a Shared DNS Zone Through a Replace-Everything API
Many registrar and DNS provider APIs expose only "replace the whole zone", with no way to add or remove a single record, so naive automation that computes its desired records and pushes them deletes every record it does not know about. This builds a read-merge-write client with an ownership marker that tells apart managed and unmanaged records, backed by a small local test server so the whole pattern can be run and verified without any real registrar.
-
Closed-Vocabulary Pydantic Validation for a Public Ingest Endpoint
Pydantic ignores fields it does not recognise by default, so a client with a typo'd field name or an out-of-vocabulary value gets a 200 response and never learns their request did not do what they thought. This shows how to close the vocabulary with extra="forbid" and Literal types, and what that choice costs in forward compatibility.
-
An Exception Hierarchy and One Handler for FastAPI Error Responses
Raising HTTPException directly from inside route and service code gives every error path its own idea of what the response body should contain, and throws away the specific context that would make the error debuggable. This builds a small domain exception hierarchy and a single handler that turns any of them into a consistent, informative response.
-
Designing a Consistent FastAPI Response Envelope
When some endpoints return a bare object, others a list, and others a hand-rolled dict with a status field, every client has to special-case each one. This works through a generic response envelope built on Pydantic generics, a custom route class that applies it without repeating boilerplate in every endpoint, and the trade-offs that come with wrapping everything uniformly.