Разработка API: баланс между новыми функциями и обратной совместимостью

Question

Сейчас я работаю над API для разработчиков функцией нашего продукта.

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

Но развертывание 2-й версии может быть проблемой для пользователей старой версии. Наш отдел маркетинга планирует значительно улучшить наш продукт API, добавить в него больше возможностей.

Как мне построить систему, поэтому
1) мы не будем ограничены «старой версией» для добавления новых интересных функций
2) нынешние пользователи API не будут недовольны из-за необходимости переделки своих систем в соответствии с измененным API

Или следует ли тестировать продукты API в песочнице в течение достаточно длительного периода времени перед общедоступным выпуском, чтобы в спецификации не было существенных изменений?

Answer 1

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

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

Если ваш язык предоставляет способы указать, что определенная функциональность устарела, он может служить для пользователей индикатором прекращения использования старых вызовов API и перехода к новым вызовам. В Java тег @deprecated javadoc может содержать примечания в документации о том, что функция устарела, или из Java 5 аннотация @Deprecated может использоваться для повышения время предупреждения о вызовах устаревших функций API.

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

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

Вот статья о Как и когда следует устаревать API от Sun, в которой может быть предоставлена ​​дополнительная информация о том, когда целесообразно объявить устаревшими части API.

Также, спасибо Дэвиду Шмитту, который добавил, что атрибут Obsolete в .NET похож на аннотацию @Deprecated в Java. (К сожалению, редактирование было перезаписано моим редактированием, поскольку мы оба редактировали этот ответ одновременно.)

Answer 2

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

Вы не указали, какой язык программирования вы используете, но и в .NET, и в Java есть механизм, который помечает определенные вызовы API как устаревшие. Если для вас очень важна обратная совместимость, вы можете выбрать тот же маршрут.

Answer 3

Это баланс, который вы должны будете достичь со своим сообществом:

• Сохраните старые функции на века, и вы получите Win32 API (30000 общедоступных функции)?

• Переписывайте API все время, и вы можете получить что-то похожее на .NET, где новая ревизия выходит очень часто (1.0, 2.0, 3.0, 3.5 ...) и ломает существующие программы или вводит новые и улучшенные способы создания пользовательского интерфейса и т. д.)

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

---

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

Answer 4

В идеале приложения, написанные для вашего исходного API, будут продолжать работать с новой версией.

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

Например, предположим, что в настоящее время у вас есть функция Foo , которая принимает 2 параметра (аргумента) в API, но вы решаете, что новая версия действительно должна принимать 3 параметра. Оставьте Foo таким, какой он есть, и добавьте новую функцию Foo2 , которая принимает 3 параметра.

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

Этот метод обычно используется Microsoft для API Windows.

Answer 5

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