主题： 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 返回带有重试提示的稳定问题类型时，自动化客户端对不可重试请求的重试次数、以及重复写入的次数，都会少于仅返回纯文字描述错误时的情况；本文提出一种对比方法。
-
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.
-
设计既保护服务又告知客户端的速率限制
按照能够验证的身份，例如账户或网络前缀，实施限制；在固定或滑动窗口中使用原子计数器，返回带 Retry-After 的429响应，为读取、写入和注册分别设置配额，并公布实际生效的限制。
-
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.
-
统一 JSON 字段的命名与大小写
为属性名选定一种大小写约定并在所有地方使用：Google 的 JSON 风格指南和 ProtoJSON 使用 lowerCamelCase，许多 API 使用 snake_case。除大小写外，还要让名称有明确含义，将枚举表示为字符串、时间戳表示为 RFC 3339 字符串、64 位整数表示为字符串。
-
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.
-
使用 JSON Schema 验证 JSON
JSON Schema 描述文档允许的结构，包括类型、必需键、枚举值、格式和边界，使各种编程语言都能在处理输入之前验证它；应明确设置 additionalProperties。
-
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.
-
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.
-
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 也借此告诉浏览器应提前获取什么。
-
HEAD 与 OPTIONS：回答什么，客户端如何使用
HEAD 相当于不带响应体的 GET：状态和标头相同，但可以省略 Content-Length 和 Vary。它可缓存，用于链接检查、大小探测和新鲜度检查。OPTIONS 查询资源或整个服务器（OPTIONS *）支持的通信选项，通常以 Allow 回答，不可缓存，也用于携带 Access-Control-Request-Method 的 CORS 预检。
-
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.
-
在 HTTP API 之上设计 SDK
SDK 应让正确调用成为最容易的选择：提供带类型的模型、保存配置的单一客户端对象、统一错误、带幂等键的重试、分页迭代器和长时间操作辅助功能。能够从 API 描述生成的部分应自动生成，只有生成方式无法表达意图时才手工编写。
-
设计接收方可信任的出站 Webhook
用覆盖正文和时间戳的 HMAC 为每次投递签名，通过重试和幂等事件 ID 提供至少一次投递，保持负载精简并附上获取详情的链接，让接收方无需在 URL 中使用秘密就能验证。
-
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.
-
有意识地选择 HTTP 状态码
状态码是客户端首先用来选择处理分支的信息：200/201/204 表示成功，304 表示未修改，400/422 表示输入有误，401/403 分别涉及凭据与权限，404 表示不存在，409/412/428 涉及冲突与前置条件，429/503 表示稍后再试。
-
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 语言协商及其局限
Accept-Language 携带带权重的语言范围列表，例如 da, en-gb;q=0.8, en;q=0.7。服务器通过 RFC 4647 的过滤或查找机制匹配已有语言，并返回 Content-Language 与 Vary: Accept-Language；标头缺失时（Googlebot 不发送它）或设置不合适时，也要合理回退，因为设备区域设置不等于读者的选择。应将它用于初次推测，而非唯一的语言选择方式。
机器可读： JSON