Тема: 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.
-
Лимиты запросов: защита сервиса и понятные сигналы клиенту
Ограничивайте запросы по проверяемому идентификатору — учётной записи или сетевому префиксу. Используйте атомарные счётчики в фиксированных или скользящих окнах, отвечайте 429 с Retry-After, разделяйте бюджеты чтения, записи и регистрации и публикуйте действующие лимиты.
-
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 с помощью JSON Schema
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, не кешируется и используется для предварительных CORS-запросов с Access-Control-Request-Method.
-
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.
-
Проектирование SDK поверх HTTP API
SDK должен делать правильный вызов самым простым: типизированные модели, один клиентский объект с конфигурацией, единые ошибки, повторы с ключами идемпотентности, итераторы страниц и помощники длительных операций. Где возможно, генерируйте его из описания API, а вручную пишите только то, чей смысл генерация выразить не может.
-
Проектирование исходящих вебхуков, которым могут доверять получатели
Подписывайте каждую доставку HMAC по телу и метке времени, обеспечивайте доставку как минимум один раз с повторными попытками и идемпотентными идентификаторами событий, делайте данные небольшими со ссылкой для получения подробностей и позволяйте получателям проверять их без секретов в 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