Устаревший веб-API: лучшие практики?

В конце концов вам нужно отказаться от частей вашего общедоступного веб-API. Однако я запутался в том, что было бы лучшим способом сделать это. Если у вас есть большая база сторонних приложений, то просто дергать старые версии API кажется неправильным способом сделать это, так как почти все приложения потерпят неудачу в одночасье. Однако вы не можете вечно сохранять доступность древних веб-интерфейсов, поскольку они могут быть устаревшими, или есть значительные изменения, которые делают невозможной работу с ним.

Каковы некоторые рекомендации для устаревших веб-API?

Похоже, что оригинальный постер уже эффективно, но неофициально устарел их API (все, что называется «старым API»). Однако до тех пор, пока он не будет объявлен, а пользователи не уведомлены о том, что API устарел, он официально не устарел.

Устаревший API - это промежуточный, неактивный этап кода. Это последние обряды. Это период, когда усыновители / потребители могут переконфигурировать свои приложения для более нового API и попрощаться, заключив мир с API. Некоторые API могут задерживаться дольше, чем другие, но на данный момент мы знаем, что их время не долгое.

Удаленный API - это похороны кода. Больше ничего он не может сделать, кроме как правильно расположенного и соответствующим образом увековеченного.

Многие разработчики API и сервисов выбирают похороны кода, а не выполняют последние обряды; однако, я думаю, что это несколько рискованно. Если было какое-либо обслуживание или обещание поддержки, которые были даны, когда API / сервис был первоначально принят или через продление, вы можете захотеть выполнить это обязательство в течение разумного периода времени перед выполнением похорон.

Для не сервисных библиотек, я думаю, что одна из основных версий, независимо от периода времени, вероятно, является более чем приемлемым и справедливым периодом гарантированной обратной совместимости. Кроме того, это зависит от влияния и лоббирования со стороны пользователей, чтобы продлить его жизнь за этот период. И не удивляйтесь, если время от времени возникают возражения из-за невосполнимых зависимостей третьих сторон, застрявших в подвешенном состоянии и привязанных к определенным версиям определенных платформ.

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

Хорошая, но не пуленепробиваемая стратегия для устаревания может заключаться в том, чтобы при объявлении устаревания выделить временной интервал для намерения удалить вместе с запросом комментариев или возражений в формате опроса рассматриваемых разделов API. Если у вас нет списка контактов пользователей, потому что ваша служба работает с [полу] анонимным доступом, вы можете рассмотреть возможность просмотра журналов для частых и активных пользователей и отправить уведомление администратору хоста или домена для переадресации по своему усмотрению.

Большинство веб-API, которые я использую (от таких компаний, как Google, Yahoo! и Microsoft), имеют период «заката». Разработчики в разумные сроки (скажем, через 3–6 месяцев) информируются о функциях, которые будут устаревшими, чтобы у них было достаточно времени для обновления заранее.

Вы можете добавить детали периодов заката в свои Условия обслуживания или другую документацию, чтобы люди знали, как это работает. Это будет означать, что когда кто-то решит использовать ваш API, он будет знать, с какими расписаниями ему нужно работать. Например, вы можете сообщить людям, что им нужно будет обновлять свою систему один раз в год и получить уведомление за 4 месяца.

Также неплохо использовать нумерацию версий, чтобы вы могли сказать, что, например, «версия 3 скоро устареет, поэтому убедитесь, что ваш код работает с версией 4» и т. Д. Таким образом, люди знают, что если их приложение работает с версией 4 тогда они готовы к закату.

Дополнительная информация с точки зрения процесса:

• Общайтесь со всеми заинтересованными сторонами . Предоставьте другим командам и потребителям API четкое и лаконичное сообщение о причине отказа от API, стратегии, деталях плана и расписания, значении версий и альтернативах, установите HTTP соответствующим образом.

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

• Управление версиями и предоставление альтернатив . Управление версиями может помочь показать изменения в основных выпусках и выработать стратегию устаревания API.

• Установите заголовок HTTP-ответа Sunset : заголовки HTTP играют техническую роль в предупреждении, потребители API должны отслеживать этот тип кода, чтобы понять, когда API становится устаревшим.

• Мониторинг до и после . Следите за своими потребителями и предупреждайте любого потребителя, что после определенного периода времени API все еще является полезной информацией, чтобы убедиться, что вы не пропустите любую оставленную программу.

В дополнение к существующим ответам вы должны предоставить замену или план миграции при удалении чего-либо, чтобы пользователи могли обновить свой код.

Старайтесь не удалять функциональность, не предоставляя альтернативы - это сделает некоторых ваших пользователей несчастными.