Оценить глазами клиента
Таблица помогает проверке, но не даёт общей гарантии. Новое поле мешает строгому читателю, новое значение перечисления — исчерпывающему разбору. Учтите клиентов, библиотеки и предположения.
| Изменение | Проверяемый риск | Нужное подтверждение |
|---|---|---|
| Удалить или переименовать поле | Чтение перестаёт работать | Явная миграция и клиентские тесты. |
| Добавить необязательное поле | Строгий читатель или конфликт имён | Тесты существующих клиентов. |
| Добавить значение в ответ | Неполный разбор вариантов | Обработка неизвестных значений. |
| Изменить значение по умолчанию | Другой бизнес-результат | Сравнение случаев без явного значения. |
Организовать сосуществование
- Опишите старые и новые структуры, значения по умолчанию, ошибки, пагинацию и права. Выполните контрактные тесты типичных случаев.
- Явно выберите механизм выбора версии. Различайте версию сервиса и документа OpenAPI; проверьте кеши и шлюзы.
- Опубликуйте сроки, руководство и контакт. Соразмерно измеряйте использование и подготовьте откат, совместимый с данными.
Отделить устаревание от отключения
Deprecation отмечает устаревший ресурс; Sunset может сообщать ожидаемое прекращение доступности. Заголовки не переносят клиентов. Перед отключением оцените оставшихся потребителей, обязательства и восстановление.
Первоисточники
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Влияние версии на потребителя
Добавление числа к URL-адресу само по себе не сохраняет существующих клиентов. Измененный тип, ожидаемое значение, поведение или ответ об ошибке могут быть несовместимы, даже если путь остается тем же.
- Инвентаризация активных клиентов и наблюдаемое использование.
- Тестирование старых версий клиентов на соответствие новому контракту.
- Публикация периода сосуществования и проверка использования перед выводом из эксплуатации.
Первичный источник: IETF RFC 9457 — Problem Details for HTTP APIs. Связанный метод: прочитать практическое руководство.
Асинхронные задания API
Принятый запрос не доказывает завершение работы.
- Аккаунт, операция и повторно используемый идентификатор
- Состояние, время, интервал и срок
- Результат, ошибка, отмена и оставшиеся эффекты
- Одно разрешённое задание и проверенный исход после обрыва
Воспроизводимый приёмочный случай
Вымышленный пример: данные не описывают клиента или наблюдаемый результат.
Посмотреть данные случая
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Ожидаемое решение
Ответ 200 при чтении статуса не означает завершения обработки. После запроса отмены вывод делают только по подтверждённому итогу.
Отмена запрошена слишком поздно
Вымышленный сценарий: одна задача J-42, секунды после отправки. Названия состояний заданы контрактом примера; HTTP их не предписывает.
| Момент | Ответ и состояние | Обоснованный вывод |
|---|---|---|
| +0 s | HTTP 202 · pending | Принято в обработку; итог ещё не подтверждён. |
| +5 s | HTTP 200 · running | Статус прочитан успешно; задача продолжает работать. |
| +6 s | HTTP 200 · cancel_requested | Запрос остановки зарегистрирован; отмена ещё не подтверждена. |
| +7 s | HTTP 200 · succeeded | Обработка завершилась раньше отмены. Покажите подтверждённый успех и проверьте последствия; не сообщайте об отмене. |
Доказывает ли 202 будущее завершение?
Нет. Он подтверждает принятие к обработке, а не конечный результат. Проверяйте состояние операции.
Первичный источник: MDN — 202 Accepted. Связанный метод: прочитать практическое руководство.
Обновление ПО: проверить смену подписанта
Решить, соответствует ли подписанный артефакт утверждённым производителю, сборке и версии.
- До проверки пакета запишите допустимого производителя, ключ или идентичность сертификата, издателя и процесс сборки. Свяжите ожидания с ПО и уже доверенным каналом подтверждения. Артефакт не должен сам определять свою политику приёма.
- Сопоставьте хеш полученного файла с объектом аттестации. Проверьте подпись заданными корнями доверия, затем идентичность, сборщик и параметры. Корректная подпись другой идентичности не удовлетворяет политике сервиса.
- Проверьте объявленную ротацию, неожиданного издателя, отсутствие подписи и другой файл. Оставьте артефакт в ожидании, если новая идентичность не подтверждена. Запишите согласование и возврат: подпись не доказывает отсутствие уязвимостей.
Воспроизводимый приёмочный случай
Вымышленный пример: данные не описывают клиента или наблюдаемый результат.
Посмотреть данные случая
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Ожидаемое решение
Вымышленный пример: хеш совпадает и подпись действительна, но подписант не утверждённый. Установка ожидает независимого подтверждения изменения.
Первичный источник: SLSA v1.2 — Verifying artifacts. Связанный метод: прочитать практическое руководство.
API: устаревание и вывод
Подробные справочные заметки в этой версии доступны на английском.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23