Кратко

  • По RFC 9457 разрешённый type URI служит основным идентификатором типа проблемы. Возможность открыть документацию не делает URI командой на загрузку, импорт схемы, повтор операции или выдачу полномочий.
  • Надёжный клиент разделяет фактический HTTP-статус, рекомендательный status, тексты для человека, единичный instance, известные расширения и локальную политику, которая может разрешить последствия.

Сервис отвечает на финансовый запрос знакомым типом проблемы с HTTPS-адресом. Клиент автоматически открывает адрес, читает недавно изменённую инструкцию и создаёт по ней новую транзакцию. Снаружи это похоже на гибкое самовосстановление.

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

URI назвал семантику, заявленную в ответе. Страница могла объяснить её разработчику. Ни адрес, ни текст не аутентифицируют ответ, не доказывают отсутствие результата первой попытки, не делают повтор безопасным и не выражают новое намерение владельца счёта.

Путаницу провоцирует универсальность URI. Он может обозначать абстрактное понятие и одновременно выглядеть как доступный сетевой адрес. Программа умеет разрешать имена, следовать перенаправлениям и загружать документы. Возможность незаметно превращается в обязанность, а читаемый текст — в исполняемое правило.

RFC 9457 проводит чёткую границу. Член type содержит ссылку URI, идентифицирующую тип проблемы. Потребитель обязан использовать URI после необходимого разрешения как основной идентификатор. При обращении к HTTP- или HTTPS-адресу желательно получить понятную человеку документацию. Но автоматически обращаться к нему не следует, кроме функций для разработчиков, например отладчика.

Так обнаружение смысла не превращается в живую производственную зависимость. Сервис публикует устойчивое определение. Клиент осознанно включает поддержку проверенных типов. Разработчик открывает документ при исследовании неизвестной ошибки. Каждый сбой не требует связи с узлом документации.

Поля рядом, полномочия порознь

Problem Details задаёт общий JSON-конверт и соответствующее XML-представление. Однако его члены отвечают на разные вопросы.

type определяет класс. Если он отсутствует, подразумевается about:blank: никаких дополнительных смыслов сверх HTTP-статуса. Клиент использует общую политику статуса, а не придумывает специальный тип из фразы.

title — короткое человеческое название типа. Оно обычно постоянно между случаями, кроме локализации, и носит рекомендательный характер. Сравнение заголовка как ключа превращает улучшение перевода в поломку протокола.

detail объясняет конкретный случай человеку. Текст должен помогать исправлению и не раскрывать внутреннее устройство. Стандарт не советует извлекать из него машинные данные. Числа и категории для программы следует определять расширениями.

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

Внешний HTTP-статус обрабатывает обычное HTTP-программное обеспечение. Член тела status лишь повторяет код, выбранный источником, и является рекомендательным. Посредник способен изменить внешний код и создать расхождение. Хранение обоих значений лучше одностороннего стирания свидетельства.

Расширения передают структурированные данные конкретного типа. Незнакомые расширения клиент обязан игнорировать. Благодаря этому определение может расти, не останавливая старых потребителей.

Такое разделение — компактная модель управления: общий минимум обеспечивает совместимость, а специальное значение и действие остаются у понимающих их сторон.

Идентификация не содержит операции

RFC 3986 описывает URI как средство отличить ресурс в некоторой области. Ресурсом бывает документ, служба, человек или абстрактное понятие; сетевой доступ не обязателен. Действия доступа, изменения и замены определяет использующий URI протокол или формат.

Поэтому неразрешимый URI способен правильно идентифицировать тип проблемы. RFC 9457 поощряет разрешимые значения ради будущей документации, а не ради обязательного запроса при каждой ошибке.

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

Относительные ссылки разрешаются относительно базового URI документа. Одинаковая строка у двух ресурсов может стать разными абсолютными типами. Поэтому RFC 9457 рекомендует абсолютные URI, когда это возможно, и предупреждает о путанице относительных значений.

Стабильность не требует всемирного эмитента типов. API вправе определять специальные значения в собственной области. Общая регистрация нужна там, где значение действительно многократно используется. Ясность совместима с децентрализацией.

Документация не должна входить в путь команд

Страница типа может объяснить смысл, рекомендуемый статус, расширения и способы решения. Она также может стать недоступной, перенаправить запрос, сменить владельца или измениться после выхода клиента. Компрометация домена позволяет подменить содержание при прежнем URI.

Автоматическое получение делает редакционные и операционные изменения производственным вводом. Путь ошибки начинает зависеть от DNS, сети, сертификата и перенаправления. Время обращения раскрывает третьей стороне, какую ошибку видит клиент. Неограниченные цели на сервере могут расширить доступную сетевую поверхность.

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

Если машине нужен путь исправления, тип может определить структурированное расширение с типизированной ссылкой. RFC 8288 помогает выразить отношение. Но ссылка не выдаёт HTTP-метод, учётные данные или согласие. Происхождение, аутентификация, авторизация, срок, безопасность повтора и намерение проверяются отдельно.

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

Человеческий текст не является скрытым API

Извлекать код или сумму из detail удобно до локализации, перестройки предложения или появления второго числа. Тогда редакционная правка неожиданно меняет машинное поведение.

Правильное распределение проще. type фиксирует семантическую идентичность, расширения несут структурированные значения, detail помогает человеку с данным случаем. Незнакомое расширение игнорируется, а не угадывается по словам.

title также можно локализовать. Программа сравнивает разрешённый URI, интерфейс показывает подходящее читателю название. Их жизненные циклы перестают конфликтовать.

Распознанный тип всё равно не доказывает истинность тела. Взломанная служба может заявить известный тип. Сохранённое тело может потерять исходный запрос. Прокси может изменить статус. Важное действие требует аутентифицированного партнёра, связи с запросом, версии договора и действующих полномочий.

Автоматизация с серьёзным эффектом должна оставить собственное обоснование: распознанные тип и расширения, локальное правило, проверенная власть, человеческое подтверждение при необходимости и конечный результат. URI входит в доказательство, но не заменяет его.

Общий реестр намеренно ограничен

RFC 9457 создал реестр IANA HTTP Problem Types для распространённых, широко используемых типов. Политика Specification Required предусматривает экспертную оценку качества определения, соблюдения стандарта и откликов сообщества. Значения только для поставщика, приложения или одной установки зарегистрировать нельзя.

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

Некоторые зарегистрированные URI с фрагментным префиксом IANA могут не разрешаться. Строка реестра и указанная спецификация всё равно задают смысл. Связываться с IANA при каждой ошибке не требуется.

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

Регистрация — не сертификат безопасности, не доказательство пригодности для каждого API и не разрешение исполнения. Она координирует слова; доверие и действие зависят от контекста.

Сделать решение о восстановлении отдельной сущностью

Сначала клиент сохраняет границу ответа: фактический статус, аутентифицированного партнёра, запрос, разрешённый абсолютный тип, instance, известные расширения и время. При расхождении остаются оба статуса.

Затем он классифицирует знание. Известному типу соответствует проверенное определение и версия обработчика. Неизвестный тип отображается и фиксируется с безопасным запасным поведением. Неизвестные расширения игнорируются. about:blank возвращает к правилам статуса.

Только потом оцениваются полномочия. Повтор зависит от метода, защиты идемпотентности и прежнего результата. Изменение счёта требует обычной авторизации. Доступ к instance требует контроля. Знакомый URI ничего не отменяет.

Наконец, поиск информации разработчиком отделяется от производственного эффекта. Контролируемый инструмент ограничивает источник и сеть, а изменение документа проходит проверку до выпуска поддержки.

Такой порядок соответствует Lu Heng: небольшой начальный стандарт, будущие решения рядом с их последствиями и информированное добровольное принятие. Не нужны центральное бюро для каждой ошибки и удалённая страница, управляющая каждым клиентом.

Источники