Проблема API-ключей, которые никогда не истекают
Ключ, выданный много лет назад, ни разу не заменённый и до сих пор действующий, это не удобство. Это риск, на который никто не смотрел уже много лет.
За скучное и стабильное версионирование API
Провайдер, объявляющий о новой мажорной версии API, обычно объявляет каждому клиенту с существующей интеграцией о проекте, которого тот не просил. Даже хорошо объявленное несовместимое изменение означает, что кому-то придётся выделить время, чтобы прочитать руководство по миграции, обновить обработку запросов или ответов, протестировать и развернуть всё это, причём в сроки, заданные дорожной картой провайдера, а не чем-либо, что происходит в собственном продукте клиента.
Мы считаем, что к стабильности API стоит относиться как к самостоятельной цели проектирования, а не как к отсутствию движения вперёд. Структура ответа после публикации должна продолжать означать то же, что и тогда, когда разработчик впервые на неё опирался. Новые поля можно добавлять как необязательные дополнения, так же как сведения о высоте, IP-угрозах и сети являются подключаемыми по желанию дополнениями поверх стандартных ответов, а не принудительной их перестройкой. Чего не должно происходить незаметно, так это изменения смысла существующего поля, переназначения кода статуса или перестройки структуры под тем же номером версии.
Отчасти несовместимые изменения так часто встречаются в этой отрасли потому, что они дёшевы для провайдера и дороги для клиента, а стороны редко напрямую обсуждают этот дисбаланс. Выпуск более чистой внутренней модели является законной инженерной победой для команды провайдера. Бременем он становится в тот момент, когда заставляет каждую зависимую интеграцию меняться в ответ, по графику, который контролирует провайдер, а не клиент.
Это не значит, что API никогда не должен меняться. Это значит, что изменения по возможности должны быть аддитивными, а там, где настоящее несовместимое изменение неизбежно, оно должно быть достаточно редким, чтобы клиент мог доверять тому, что структура, на которую он опирался, будет работать и через месяцы или годы, а не следить за журналом изменений, чтобы защититься. Стабильность не равна застою. Это обещание того, что к сегодняшней работе над интеграцией не прикреплён срок годности, о котором вам никто не сказал.
У нас есть и эгоистичная причина придерживаться этой позиции, помимо доброго отношения клиентов. Каждый совместимый хост, который мы поддерживаем, зависит от точного воспроизведения структуры другого провайдера на протяжении времени, а это работает, только если на воспроизведённые структуры можно полагаться как на стабильные цели. Компания, которая относится к собственному API как к одноразовому и перерабатывает его всякий раз, когда удобно, это компания, чьи гарантии совместимости тоже на самом деле не являются гарантиями. Стабильность должна быть привычкой, которая действует везде, иначе она не действует нигде.
«Скучный» здесь не упрёк. Версия API, которая спустя годы работает точно так же, как в момент вашей первой интеграции, не доказывает, что ничего не улучшилось. Она доказывает, что улучшения происходили так, что вам не нужно было их замечать, и в этом весь смысл хорошей дисциплины версионирования.