テーマ： 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.

  article · de · reviewed · 知識の基準日 2026-09-16

• 機械可読なエラータイプはエージェントによる有害なリトライを減らす

  仮説: APIが安定したproblemタイプとリトライのヒントを返す場合、自動化されたクライアントは、文章だけのエラーメッセージのときと比べて、リトライすべきでないリクエストの再試行や、書き込みの重複が少なくなる。比較検証を提案する。

  hypothesis · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  methodology · en · reviewed · 知識の基準日 2026-09-21

• サービスを守り、クライアントに伝わるレート制限の設計

  検証できる識別情報、例えばアカウントやネットワークプレフィックスごとに制限する。固定窓またはスライディング窓で原子的なカウンターを使い、429と Retry-After を返す。読み取り、書き込み、登録の枠を分け、実効的な制限を公開する。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• Stripe API pagination and idempotency keys: starting_after, has_more and the 24-hour window

  Stripe's v1 list endpoints paginate with the mutually exclusive starting_after/ending_before cursor parameters (limit 1-100, default 10) and a has_more flag, with client-library auto-pagination helpers to walk every page; POST requests can carry an Idempotency-Key whose saved result Stripe replays for about 24 hours, after which keys may be pruned. Rate-limited requests get 429 with a Stripe-Rate-Limited-Reason header.

  article · en · reviewed · 知識の基準日 2026-09-25

• JSON フィールドの命名と大文字・小文字を統一する

  プロパティ名の表記規則を一つ選び、すべてに適用します。Google の JSON スタイルガイドと ProtoJSON は lowerCamelCase を使い、多くの API は snake_case を使います。表記だけでなく、意味のある名前を付け、列挙値は文字列、タイムスタンプは RFC 3339 の文字列、64 ビット整数は文字列にします。

  article · ja · reviewed · 知識の基準日 2026-09-15

• The Standard Webhooks spec versus Shopify's HMAC header and GitLab's shared-secret token

  The Standard Webhooks specification defines webhook-id, webhook-timestamp and webhook-signature headers, a whsec_-prefixed base64 secret whose decoded bytes are the HMAC key, and a v1,<base64> signature over "{id}.{timestamp}.{payload}"; GitLab's signing tokens (GitLab 19.0, generally available in 19.1) implement exactly this. Shopify instead sends a base64 HMAC of the raw body in X-Shopify-Hmac-SHA256, and GitLab's older X-Gitlab-Token is a plain shared secret, not an HMAC at all.

  article · en · reviewed · 知識の基準日 2026-09-25

• JSON Schema による JSON の検証

  JSON Schema は、型、必須キー、列挙値、形式、範囲など、文書で許容される構造を記述する。さまざまな言語で入力を処理前に検証できるようにし、additionalProperties は明示的に設定する。

  article · ja · reviewed · 知識の基準日 2026-09-15

• Idempotente Operationen und sichere Wiederholungen entwerfen

  Eine Operation ist idempotent, wenn ihre mehrfache Ausführung dieselbe Wirkung hat wie eine einzelne; RFC 9110 legt das für HTTP-Methoden fest, und ein Idempotency-Key-Header überträgt die Eigenschaft auf POST. Schlüssel samt Fingerabdruck und Ergebnis speichern, Konflikte mit 409 und 422 melden, Schlüssel nach dokumentierter Frist löschen.

  methodology · de · reviewed · 知識の基準日 2026-09-16

• 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.

  methodology · en · reviewed · 知識の基準日 2026-09-21

• 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.

  methodology · en · reviewed · 知識の基準日 2026-09-16

• Link ヘッダーとリンク関係型

  RFC 8288 は、任意の HTTP レスポンスが Link ヘッダーで型付きリンクを伝える方法を定義する。形式は <target>; rel="relation" で、anchor、hreflang、type、title、media を追加できる。関係名は IANA 登録名（next、prev、canonical、alternate、describedby、preload）または独自拡張用の絶対 URI を使う。HTML 以外の応答から関連リソースを示し、103 Early Hints で先行取得を促す仕組みである。

  article · ja · reviewed · 知識の基準日 2026-09-16

• HEAD と OPTIONS：何を回答し、クライアントは何に使うか

  HEAD は本文のない GET であり、ステータスとヘッダーは同じだが、Content-Length と Vary は省略できる。キャッシュ可能で、リンク、サイズ、鮮度の確認に使う。OPTIONS はリソースまたはサーバー全体（OPTIONS *）の通信オプションを問い合わせ、通常は Allow を返す。キャッシュ不可で、Access-Control-Request-Method を伴う CORS プリフライトにも使う。

  article · ja · reviewed · 知識の基準日 2026-09-16

• Verifying Slack request signatures: X-Slack-Signature, the 5-minute replay window and the 3-second rule

  Slack signs requests as v0=<hex HMAC-SHA256> of the string "v0:{timestamp}:{raw body}" in the X-Slack-Signature header, paired with X-Slack-Request-Timestamp, which Slack's own example rejects once it differs from local time by more than five minutes. Slash commands and interactive payloads must additionally be acknowledged within three seconds, before any slow processing.

  article · en · reviewed · 知識の基準日 2026-09-25

• HTTP API の上に SDK を設計する

  SDK は、正しい呼び出しを簡単に行えるようにするべきである。型付きモデル、設定を保持する単一のクライアントオブジェクト、統一されたエラー、冪等性キー付きの再試行、ページ分割のイテレーター、長時間操作のヘルパーを備える。可能な部分は API 記述から生成し、生成では意図を表せない部分だけを手書きする。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• 受信側が信頼できる送信 Webhook を設計する

  本文とタイムスタンプを対象とした HMAC で各配信に署名し、再試行と冪等なイベント ID で少なくとも一回の配信を行う。ペイロードは小さく保って詳細取得用のリンクを付け、URL にシークレットを入れずに受信側が検証できるようにする。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  article · en · reviewed · 知識の基準日 2026-09-15

• HTTP ステータスコードを意図して選ぶ

  クライアントが最初に処理を分岐させるのはステータスコードです。成功には 200/201/204、未変更には 304、不正な入力には 400/422、認証情報と権限の区別には 401/403、不在には 404、競合や前提条件には 409/412/428、後で再試行する場合には 429/503 を使います。

  article · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  article · en · reviewed · 知識の基準日 2026-09-21

• Accept-Language による言語ネゴシエーションとその限界

  Accept-Language は重み付きの言語範囲リスト（da, en-gb;q=0.8, en;q=0.7）を送る。サーバーは RFC 4647 のフィルタリングやルックアップで利用可能な言語と照合し、Content-Language と Vary: Accept-Language を返す。ヘッダーがない場合（Googlebot は送らない）や不適切な場合にも合理的にフォールバックする必要がある。端末のロケールは読者の選択とは限らないため、最初の推測に使い、唯一の選択手段にはしない。

  article · ja · reviewed · 知識の基準日 2026-09-16

次のページ

機械可読： JSON