Стандарты
компаний

В предыдущих модулях правила подкреплялись ссылками на своды Zalando, Microsoft, GitHub, adidas, DigitalOcean и Box. В этой главе они рассмотрены вместе: что в них совпадает, в чём они расходятся и как этим пользоваться при выборе решения для своего проекта.

Категория: Репозиторий
Уровень: Базовый
Связанные главы: 6.1 API Style Guide · 5.2 Breaking changes · 5.1 Четыре номера
Зачем это знать: Чтобы обосновывать решения ссылкой, а не мнением

§1Пять сводов и чем они отличаются

Свод	Объём	Форма	Чем полезен
Zalando	Очень большой	Пронумерованные правила с уровнями	Готовый ответ почти на любой вопрос и номер для ссылки
Microsoft	Большой	Отдельные документы для Azure и Graph	Видно, как расходятся решения внутри одной компании
adidas	Небольшой	Связанные разделы в Markdown	Образец свода для команды, которой не нужен том
DigitalOcean	Средний	Набор правил линтера	Стандарт в исполняемом виде
Box	Средний	Репозиторий описания с правилами вокруг него	Видно устройство репозитория публичного API целиком

Репозиторий microsoft/api-guidelines с отдельными папками azure и graph — **Два свода в одном репозитории.** У Microsoft отдельные правила для Azure и для Microsoft Graph, и они расходятся в важных решениях — например, в том, где указывать версию API. Это лучший аргумент против фразы «в индустрии принято».

Репозиторий adidas/api-guidelines с компактным сводом правил — **Компактный свод.** adidas показывает, что полезный стандарт не обязан быть томом: он читается за вечер и покрывает те же основные темы — адреса, методы, коды, ошибки, версии.

§2Где все сходятся

Часть решений совпадает во всех рассмотренных сводах. Эти решения и можно называть общепринятыми; отступление от них требует отдельного обоснования.

Адрес — существительноеДействие выражается методом, а не именем пути. Ни один свод не предлагает /getTickets.единогласно

Код ответа описывает исход200 не возвращается вместо 201 или 404, ошибка не прячется в теле успешного ответа.единогласно

Единый формат ошибокФормат может быть свой, но он один на весь API и содержит машиночитаемый признак вида ошибки.единогласно

Версия объявлена явноГде именно — расходятся, но что версия должна быть видна клиенту, согласны все.единогласно

Совместимость определена письменноЧто считать поломкой, решает владелец API, но решение должно быть записано.единогласно

Описание машиночитаемоOpenAPI как формат контракта не оспаривает никто из пятерых.единогласно

§3Где расходятся

Вопрос	Варианты	Где разбирали
Где указывать версию	Путь (Graph) · заголовок (GitHub) · параметр запроса (Azure) · имя файла (Box)	глава 5.1
Новое поле в ответе	Совместимо (GitHub) · несовместимо (Azure)	глава 5.2
Формат ошибки	Problem Details (Zalando) · своя структура плюс заголовок (Azure) · своя структура со ссылкой (GitHub)	глава 4.1
Единица в `X-RateLimit-Reset`	Секунды до сброса (Zalando) · момент времени UTC epoch (GitHub)	глава 4.3
Идентификатор запроса	`X-Flow-ID` (Zalando) · `x-ms-client-request-id` (Azure) · `X-Request-Id` (распространённый)	глава 4.3
Идемпотентность `POST`	MAY (Zalando) · обязательна на практике (Stripe) · не описана у многих	глава 4.3

В каждой из шести строк допустимо несколько решений. Поэтому требование «сделать по стандарту» неполно: нужно указать, по какому именно.

§4Как выбирать между вариантами

Посмотрите, кто ваши клиенты. Это решает больше всего: у публичного API и у трёх внутренних сервисов разные ответы почти на все спорные вопросы.
Возьмите вариант, который дешевле поддерживать. Версия в пути видна в журналах; версия в заголовке не засоряет адреса. Любой выбор здесь — компромисс.
Проверьте, чем будете проверять. Правило, которое нечем проверить, работать не будет — как бы солидно ни выглядел его источник.
Запишите решение и отвергнутые варианты. ADR из главы 5.4. Через год вопрос зададут снова.
Не смешивайте варианты в одном API. Часть операций с версией в пути, часть в заголовке — худший из возможных исходов.

§5Как ссылаться на источник

Ссылка на правило в своём стандарте должна выдержать два испытания: её можно открыть, и открывший увидит именно то, о чём речь.

Плохая ссылка

«как принято в индустрии»
«см. документацию Zalando»
ссылка на главную страницу свода
пересказ своими словами без цитаты

Хорошая ссылка

Zalando, правило 176 «MUST support problem JSON»
адрес с якорем на конкретное правило
цитата в оригинале
перевод под цитатой

По этому правилу построен и справочник: рядом с каждым требованием стандарта приведены английский оригинал, перевод и адрес источника. Правило без проверяемого источника нельзя отличить от личного мнения автора.

Проверяйте статус документа

У RFC он указан в начале: Standards Track, Informational, Experimental. У черновиков IETF бывает пометка «expired» — так случилось с Idempotency-Key из главы 4.3. Статус не запрещает пользоваться решением, но определяет, на что вы опираетесь: на стандарт или на сложившуюся практику.

§6Три уровня доказательности

Уровень	Что это	Примеры из справочника
Стандарт	RFC со статусом Standards Track	RFC 9110 (методы), RFC 9457 (ошибки), RFC 9745 (Deprecation)
Практика, описанная документом	Informational RFC, черновик, спецификация вне IETF	RFC 8594 (Sunset), Semantic Versioning, Keep a Changelog
Правила компании	Свод конкретной организации	Zalando 176, GitHub API Versions, Azure Breaking changes

Уровни говорят не о качестве решения, а о том, насколько широко оно согласовано. Отступление от правила компании обсуждают внутри команды. Отступление от документа со статусом Standards Track означает несовместимость с чужими инструментами, которые на этот стандарт опираются.

§7Сводная таблица решений проекта

Ниже собраны решения учебного проекта и их источники — сокращённое содержание файла docs/STANDARDS.md.

Решение проекта	Источник	Уровень
Ошибки в `application/problem+json`	RFC 9457 · Zalando 176	стандарт
Метаданные `info` заполнены	Zalando 218	правила компании
Версия контракта по SemVer	Semantic Versioning 2.0.0 · Zalando 116	практика
Мажорная версия в пути `/api/v1`	Microsoft Graph · ADR 0001	правила компании
Новое поле ответа считается совместимым	GitHub API Versions	правила компании
`Deprecation` и `Sunset` в ответах	RFC 9745 · RFC 8594 · Zalando 189	стандарт и практика
`ETag` с `If-Match` и `If-None-Match`	RFC 9110 · Zalando 182	стандарт
`429` с `Retry-After` и `X-RateLimit-*`	RFC 6585 · Zalando 153	стандарт и правила компании
`Idempotency-Key` с хранением 24 часа	Zalando 230 · Stripe	практика
Журнал изменений	Keep a Changelog	практика

Ни в одной из десяти строк источником решения не является удобство разработчика. Этим стандартизованный API отличается от просто аккуратно написанного.

§8Частые ошибки

«В индустрии принято»По половине вопросов индустрия не сходится. Называйте конкретный источник.

Копировать чужой свод целикомПравила Zalando написаны под масштаб Zalando. Берут решения, а не объём.

Ссылка на главную страницу сводаЧитатель не найдёт нужное правило. Нужен адрес с якорем и номер.

Игнорировать статус документаЧерновик мог истечь, Informational не обязывает. Это влияет на то, как вы обосновываете решение.

Смешивать варианты в одном APIЧасть операций по одному правилу, часть по другому — хуже любого последовательного выбора.

Брать чужой свод и не адаптировать проверкиПравило без способа проверки не работает, из какого бы свода оно ни пришло.

§9Проверьте себя

Назовите три решения, в которых сходятся все рассмотренные своды.
Назовите три вопроса, по которым они расходятся, и укажите варианты.
Почему расхождение между сводами Azure и Microsoft Graph — полезный аргумент в споре?
Из чего состоит хорошая ссылка на правило чужого свода?
Чем отличается отступление от Standards Track RFC от отступления от правила компании?
Возьмите любую строку сводной таблицы §7 и объясните, почему решение именно такое.

СводыZalando — подробныйMicrosoft — два разныхadidas — компактныйDigitalOcean — как кодBox — репозиторий

Сходятсяадрес — существительноекод описывает исхододин формат ошибокверсия объявлена

Расходятсягде версияновое поле в ответеформат ошибкиединица RateLimit-Reset

Ссылканомер правилаякорь в адресецитатаперевод

Справочник «Стандартизация HTTP API» · модуль 7 · глава 7.4Макаров Максим Николаевич