Версии
Путь /v1, аддитивные изменения, устаревание.
Мажорная версия — в пути, /v1, и остаётся там на весь срок жизни версии. Внутри мажора — только
аддитивные изменения: новая операция, новое необязательное поле запроса, новое поле ответа, новое
значение enum (в полях, помеченных как расширяемые), новый код ошибки, новый тип события, ослабление
валидации. Ничего из этого не должно ломать корректно написанный клиент — если ваш код падает на
нераспознанном поле JSON или значении enum, это ошибка клиента, а не нарушение контракта.
Ломающие изменения ждут v2. Когда выйдет v2, v1 продолжит работать минимум 12 месяцев, с баннером
устаревания в документации и сигналом Sunset в ответах. Удаление или переименование кода ошибки
считается ломающим изменением — как и удаление поля.
Где следить за изменениями: changelog, с фильтром по продукту и явной пометкой каждой ломающей записи — не полагайтесь на то, что API молчаливо остаётся прежним между двумя чтениями одного эндпоинта.
Далее: Ошибки