api-design
Response shapes, error models and contracts a client can rely on.
-
Tracking Meals and Automating Shopping With an MCP Server
An MCP server for meal tracking and grocery shopping automation: planned meals minus live stock, and why the v2 rebuild derives stock from an event journal.
-
Building a Headless Storefront Against the OpenTaberna API
A headless storefront for OpenTaberna: a 37-line API client, TypeScript types generated from OpenAPI, and a compiler that catches field typos.
-
OpenTaberna: Headless, Open-Source E-Commerce You Self-Host
OpenTaberna is headless, open-source e-commerce: an Apache-2.0 shop API on FastAPI and PostgreSQL that you self-host with Docker Compose.
-
Turning Alertmanager Webhooks Into Retained MQTT State
Alertmanager webhook to MQTT retained messages: clear stale state on resolve with an empty retained payload, keeping current alerts in Redis by fingerprint.
-
OIDC Client Shapes: A Token-Validating API Is Not a Login Client
Keycloak directAccessGrantsEnabled on a token-validating API lets it mint tokens. bearerOnly client, oidc-audience-mapper and a PyJWT aud check.
-
Separating 'Cannot Ever' From 'Currently Broken' in Sweep Automation
Sweep automation: a 404 cannot tell "never supported" from "currently broken". An explicit cannot-ever allowlist with required reasons, and its tests.
-
Designing a Docker Image Build API: Job Model and Streamed Logs
Docker SDK ImageBuild returns a nil error when RUN fails: read the error field in the JSON build stream. A Go job model with POST /builds and live logs.
-
A 500 That Was a Misconfigured Client, Not an Auth Failure
resp.json()["active"] raises KeyError when token introspection returns 401 invalid_client. Check the status code first and report a client config error.
-
An OpenAI-Compatible Proxy in Front of a Local Model Server
/v1/chat/completions behind a FastAPI proxy: bearer API-key auth, unbuffered SSE streaming, and a /healthz that cannot trigger a model load.
-
One Dashboard on Five Unrelated Backends: Normalising at the Boundary
asyncio.gather with return_exceptions=True in a FastAPI BFF: map two upstream APIs onto one schema and return partial data with health when one is down.
-
Idempotent Payment Webhooks with a Deduplication Table
Payment webhook processed twice on retry: dedupe on the provider event ID with a primary key, committed in the same transaction as the side effect.
-
Modelling an Order Lifecycle as an Explicit State Machine
Python order status as a state machine: a transition table and one transition_to method that raises InvalidTransition on moves like shipping a cancelled order.
-
Managing a Shared DNS Zone Through a Replace-Everything API
PUT /zone replaces the whole DNS zone: a read-merge-write client with owner TXT records that keeps unmanaged records and removes stale managed ones.
-
Closed-Vocabulary Pydantic Validation for a Public Ingest Endpoint
Pydantic extra="forbid" and Literal types return 422 for typo'd fields and unknown values that the default extra="ignore" silently drops.
-
An Exception Hierarchy and One Handler for FastAPI Error Responses
FastAPI add_exception_handler on a base AppError instead of raising HTTPException in services: one status-code mapping and a consistent error body.
-
Designing a Consistent FastAPI Response Envelope
FastAPI response envelope with Pydantic Generic[T] and a custom APIRoute get_route_handler that wraps every response in success, data and error.