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

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

Что имеет версию

Файл контракта. info.version файла OpenAPI, сейчас 1.0.0, и версия в пути: /v1 на хосте verify, /api/v1, /d/v1, /s/v1.
Пакет показов. Поле schema пакета, сейчас tanba.pop/1.
Подписанные файлы. У списка отзыва, печати и якоря в подписанном теле есть v, а у файла входных данных дня реестра своя v.
Статус подключения на этом сайте: работает, бета или черновик.

Статусы

Статус	Что значит	Уведомление до несовместимого изменения
Работает	Стабильно. Рассчитано на то, чтобы на него опираться	Не меньше 12 месяцев
Бета	Работает и используется, но еще может измениться. Протокол устройства и файлы доказательств остаются бета, пока идентификаторы подписанных атрибутов лежат во временной дуге	Не меньше 30 дней, когда это возможно; в журнале изменений сказано, что изменилось
Черновик	Предложение. Не попадает в индекс поисковых систем	Не предусмотрено

Изменения, которые не ломают

Мы вносим их в любое время и без уведомления в текущей версии. Ваш клиент должен их выдерживать:

новая операция, новый необязательный параметр, новое поле в ответе или в подписанном теле;
новое значение в списке значений, например новый флаг, причина отказа, название события или code ошибки;
более длинный текст, новый заголовок, другой порядок полей.

Поэтому игнорируйте поля, которых не знаете, и считайте неизвестное значение «прочим», а не ошибкой. Ориентируйтесь на code, а не на тексты title или detail.

Несовместимые изменения

Эти изменения ломают клиентов и выходят только в новой основной версии, рядом со старой:

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

У новой основной версии свой путь (/v2) или своя schema (tanba.pop/2). Старая версия продолжает работать весь срок уведомления.

Как проходит снятие с поддержки

Операция или поле помечается устаревшим в справочнике и в файле OpenAPI (deprecated: true) с указанием, чем заменить, и даты, когда оно перестанет работать.
В журнале изменений в тот же день появляется запись.
Устаревшее работает до этой даты. Срок уведомления берется из статуса по таблице и считается от записи в журнале изменений.
После этой даты оно удаляется, и журнал изменений сообщает об этом.

Исключения ради безопасности и закона

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

Где смотреть

Каждое изменение контракта записано в журнале изменений, новейшие сверху, простыми словами. Файлы OpenAPI на странице каждого подключения это исходник этого сайта, поэтому клиент, созданный по ним, всегда совпадает со страницами.