С чего начать
Версионирование и вывод из эксплуатации
Мажорные версии в URL, совместимые дополнения, уведомления об устаревании и сроки отключения.
Стабильные пути мажорных версий
Клиентские интеграции используют мажорную версию в URL — сейчас это /api/v1. Основанное на дате значение info.version в OpenAPI идентифицирует точный опубликованный контракт в рамках этой мажорной версии.
Совместимые изменения
В рамках v1 SendHQ может добавлять необязательные поля запроса, поля ответа, значения перечислений (там, где это допускает схема) и новые операции. Клиентам следует игнорировать неизвестные поля ответа и не считать перечисление навсегда закрытым, если в схеме не сказано иное.
Несовместимые изменения
Несовместимое изменение запроса, ответа, аутентификации или поведения требует нового мажорного пути, например /api/v2, документации по миграции и объявленного переходного периода. Текущий API v1 не объявлен устаревшим.
Устаревание и отключение
Когда версия объявляется устаревшей, SendHQ документирует замену и путь миграции и, где применимо, возвращает заголовки Deprecation и Sunset. Устаревшие версии остаются доступными не менее 90 дней после опубликованной даты устаревания, если только их дальнейшая работа не создаёт срочного риска для безопасности или юридического риска.