Кратко

  • RFC 9727 определяет /.well-known/api-catalog и отношение api-catalog, чтобы издатель мог объявить набор API. Стандарт не удостоверяет владение, разрешение, достижимость, мониторинг или состояние каждого элемента.
  • У корневого, внешнего и вложенного каталогов свои издатели, контексты, кэши и сроки обновления. Такая топология — граф датированных утверждений, а не автоматически наследуемое доверие.
  • Удаление item доказывает изменение публикации. Надёжный вывод требует отдельных данных об экспозиции, трафике, зависимостях, выполнении изменения, откате и последующем наблюдении.

Запись уже исчезла, а адрес ещё отвечает

RFC 9727 опубликован в феврале 2025 года как документ Standards Track IETF. Механизм намеренно мал: издатель отвечает по /.well-known/api-catalog, может сообщить адрес заголовком Link и возвращает Linkset JSON. Отношение item перечисляет API, api-catalog связывает подкаталоги.

Это полезно, потому что сведения об API разбросаны по конфигурациям развёртывания, шлюзам, порталам и частным таблицам. Стандартная точка превращает фрагменты памяти в машиночитаемое заявление. Но заявление не становится полной копией работающей инфраструктуры.

RFC 8288 описывает типизированные отношения, а не эксплуатационные сертификаты. Корректный item не доказывает разрешение DNS из конкретной сети, наличие listener, владение целью, принятие учётных данных или успешную бизнес-транзакцию. Неуказанный listener тоже не исчезает.

OWASP API9:2023 относит старые версии, недокументированные хосты и неясные среды к рискам поверхности атаки. RFC 9727 уменьшает слепую зону, если список сверяют с инфраструктурой. Подсчёт ссылок создаёт лишь более опрятную ложную уверенность.

Полномочие проверяется для каждой связи

Каталог под доменом издателя может указывать на партнёра, управляемый сервис, регион или исторический маршрут. Доказано только решение опубликовать связь. Кто владеет целью и вправе её менять, устанавливается отдельно.

RFC 9727 разрешает направить к каталогу на другом домене, если well-known ресурс нельзя разместить у себя. Тогда ответ обнаружения, перенаправления, TLS-идентичности, время и хэш образуют цепочку публикации. Одинаковое название не подтверждает непрерывность полномочий после смены цепочки.

Вложенность умножает границы. Корпоративный каталог ведёт к продуктам, продукты — к регионам с разными командами и циклами. RFC 9264 требует явного контекста: Linkset без anchor способен означать другое. Это граф датированных рёбер, а не дерево наследуемой истины.

Полезная квитанция хранит домен, путь, redirects, TLS-сторону, время, тип данных, profile, ETag или Last-Modified, хэш и каждую тройку контекст–цель–отношение. Первая и последняя фиксации не превращаются автоматически в даты создания и удаления. Это аналитическое предложение, не новое требование RFC.

У кэша и API разные часы

RFC 9111 различает свежесть, повторную проверку и устаревшие ответы. ETag подтверждает одинаковое представление между проверками, не непрерывную работу API. Долгая свежесть задерживает срочное удаление; короткая увеличивает нагрузку, но не исправляет плохо обслуживаемый источник.

Следует разделять время намерения издателя, ответа origin, проверки или повторного использования кэша, изменения шлюза и самого наблюдения. «Не было в каталоге в 14:00» проверяемо при сохранённом ответе и пути кэша. Это не «отключено в 14:00».

RFC 9727 рекомендует измерять доступность и производительность каталога, сопоставлять его чтение с последующими вызовами, удалять устаревшие элементы, проверять синтаксис и бизнес-правила, включать обновление в release-цикл. Главное: каталог дополняет систему управления API, а не заменяет её.

Здоровый каталог не лечит больной API

Проверка может скачать каталог, подтвердить JSON и пройти все уровни, пока один item постоянно ошибается. И наоборот, каталог может упасть, а клиенты с известными адресами — работать. Отношение status из RFC 8631 указывает на ресурс состояния, но не объединяет статус, каталог и транзакцию в одно измерение. TCP-соединение, HTTP-ответ и аутентифицированная операция — разные наблюдения.

RFC 9727 предупреждает и о раскрытии внутренних API. TLS, проверка, минимальные права записи, rate limit и контроль доступа защищают публикацию, но не доказывают, что внутренний endpoint недоступен снаружи. Чтение списка не даёт права вызывать цели.

Удаление карточки не закрывает сокет

Аудит каталога помогает находить zombie API без поддержки, мониторинга или исправлений. Они опасны именно потому, что административная запись разошлась с работающей системой. Находка начинает вывод, а не удостоверяет его.

item удаляют при исправлении, переносе, сокрытии, замене или запланированном выводе. Это не закрывает listener, не отзывает secret, не удаляет DNS, не опустошает очередь и не мигрирует неизвестный клиент. Сохранение записи также не доказывает поддержку.

Квитанция вывода должна связать последний снимок и полномочное решение с изменениями DNS, маршрутизации, балансировщика и шлюза; затронутыми средами; владельцами и зависимыми задачами; трафиком с окном и слепыми зонами; учётными данными и потоками; подтверждением исполнения; владельцами исключения и отката; последующими пробами. Квартальная задача вне окна остаётся неизвестной, а не нулевой.

Отдельная статья BTW уже разбирает Deprecation и Sunset как сигналы миграции. Здесь граница иная: удалённое ребро каталога не является доказательством исполнения. Сервер может отвечать после удаления или исчезнуть до обновления ссылки. Расхождение нужно сохранять.

Источники

Спецификации и реестры: RFC 9727, RFC Editor, IETF Datatracker, IANA well-known, IANA link relations, RFC 9264, RFC 8288, RFC 8615, RFC 8631, RFC 9111, RFC 9745, RFC 8594, OWASP API9:2023.

Атрибутированная аналитическая рамка: Lu Heng, Note 64, приоритет работающего кода, зачем BTW фиксирует реальность.