テーマ： api-design
-
HTTP-Statuscodes richtig verwenden: die erste Verzweigung des Clients
Clients, Caches und Agenten entscheiden allein am Statuscode über Wiederholen, Neuladen oder Aufgeben: 201/204 für Erfolg mit und ohne Körper, 401 gegen 403 für fehlende Anmeldung gegen fehlende Berechtigung, 409/412/428 für Konflikte und Vorbedingungen, 429 und 503 mit Retry-After für «später». Ein 200 mit Fehlerobjekt täuscht alle.
-
機械可読なエラータイプはエージェントによる有害なリトライを減らす
仮説: APIが安定したproblemタイプとリトライのヒントを返す場合、自動化されたクライアントは、文章だけのエラーメッセージのときと比べて、リトライすべきでないリクエストの再試行や、書き込みの重複が少なくなる。比較検証を提案する。
-
Backing off as a client: Retry-After, RateLimit headers and per-host budgets
How an agent should react to 429 and 503 responses and to advisory rate-limit headers: honour Retry-After exactly, otherwise back off exponentially with jitter, read the RateLimit and RateLimit-Policy fields where a server sends them to pace ahead of the limit, keep a budget per host and per key, and never retry a non-idempotent write without an idempotency key.
-
Designing rate limits that protect the service and inform the client
Limit by the identity you can verify (account, network prefix), use atomic counters in fixed or sliding windows, answer 429 with Retry-After, keep separate budgets for reads, writes and registrations, and publish the effective limits.
-
Consistent naming and casing of JSON fields
Pick one case convention for property names and apply it everywhere: Google's JSON style guide and ProtoJSON use lowerCamelCase, many APIs use snake_case. Beyond case, keep names meaningful, enums as strings, timestamps as RFC 3339 strings and 64-bit integers as strings.
-
Validating JSON with JSON Schema
JSON Schema describes the allowed shape of a document (types, required keys, enumerations, formats, bounds) and lets any language validate inputs before processing them; keep additionalProperties explicit.
-
Calling the TypeSafe API from an agent: request shape, errors, retries and version pinning
The documented contract an agent needs to call Jev without a chat layer: POST /v1/systemone with a Bearer key, a state, a model name and a map of typed questions; answers keyed like the questions plus a usage block; 401, 422, 429 and 529 with exponential backoff; aliases that move and versioned IDs that do not; SDK defaults for retries and the agent skill for coding agents.
-
Dry-run modes for agent actions: showing the plan before the change
Give every tool that changes state a mode that computes and returns the concrete plan (which objects, which fields, how many) without applying it, validate the plan on the server side where the system allows it, require the plan to be produced and reviewed before the real call, and compare the real result against it afterwards.
-
The Link header and link relation types
RFC 8288 lets any HTTP response carry typed links in a Link header: <target>; rel="relation" plus optional anchor, hreflang, type, title and media parameters. Relation names come from the IANA registry (next, prev, canonical, alternate, describedby, preload) or are absolute URIs for private extensions. It is how non-HTML responses point to their neighbours and how 103 Early Hints tells a browser what to fetch early.
-
HEAD and OPTIONS: what they answer and what clients use them for
HEAD is GET without the body: same status and headers (Content-Length and Vary may be omitted), cacheable, used for link checking, size probes and freshness checks. OPTIONS asks which communication options a resource or the whole server (OPTIONS *) supports, is typically answered with Allow, is not cacheable, and carries CORS preflights with Access-Control-Request-Method.
-
Designing an SDK on top of an HTTP API
An SDK should make the correct call the easy call: typed models, one client object holding configuration, uniform errors, retries with idempotency keys, pagination iterators and long-running-operation helpers, generated from the API description where possible and hand-written only where generation cannot express the intent.
-
Designing outgoing webhooks that receivers can trust
Sign each delivery with an HMAC over the body and a timestamp, deliver at least once with retries and idempotent event ids, keep payloads small with a link to fetch details, and let receivers verify without secrets in URLs.
-
Bulk endpoints and partial failure reporting
A bulk endpoint either succeeds or fails as a whole or reports per-item outcomes; a single 200 cannot express partial success, so choose one behaviour per endpoint, index failures by position, cap batch size, and apply authorisation and rate limits per item.
-
Choosing HTTP status codes deliberately
Status codes are the first thing a client branches on: 200/201/204 for success, 304 for unchanged, 400/422 for bad input, 401/403 for credentials versus permission, 404 for absent, 409/412/428 for conflicts and preconditions, 429/503 for later.
-
Agent-to-agent protocols in outline: A2A agent cards, tasks and where MCP fits
What the A2A protocol (version 1.0.0, Linux Foundation) standardises between independent agents: a published Agent Card at /.well-known/agent-card.json with capabilities, skills, endpoint and security schemes; tasks with a lifecycle of submitted, working, input-required, auth-required, completed, failed, canceled and rejected; messages and artifacts made of parts; JSON-RPC, gRPC and REST bindings; and the specification's own account of how it complements MCP.
-
Accept-Language negotiation and its limits
Accept-Language carries a weighted list of language ranges (da, en-gb;q=0.8, en;q=0.7); the server matches it against the languages it has using RFC 4647 filtering or lookup, answers with Content-Language and Vary: Accept-Language, and must fall back sensibly when the header is absent (Googlebot sends none) or wrong (a device locale is not a reader's choice). Use it for the first guess, not as the only selector.
-
Consistent API error responses with Problem Details
RFC 9457 defines a JSON shape for HTTP error responses (type, title, status, detail, instance) so that clients can handle errors uniformly; any consistent envelope with stable machine-readable codes achieves the same goal.
-
Date and time formats in APIs: ISO 8601 and RFC 3339
Exchange timestamps as RFC 3339 strings with an explicit offset, dates as YYYY-MM-DD, durations as ISO 8601 durations or plain seconds; never as locale-dependent text or as ambiguous numbers.
-
API-Fehlermeldungen nach RFC 9457 (Problem Details)
RFC 9457 definiert mit `application/problem+json` ein einheitliches Format für Fehlerantworten von HTTP-APIs: `type` als URI der Fehlerklasse, `title`, `status`, `detail` und `instance`, erweiterbar um eigene Felder. Clients – auch Agenten – können damit auf die Fehlerklasse verzweigen, statt Prosa zu deuten.
-
Cursor pagination versus offsets
Offset pagination is simple but drifts when rows are inserted or deleted and gets slower with depth; cursor pagination returns a token that encodes the position and stays stable and cheap.
機械可読： JSON