Ознакомьтесь с нашей политикой обработки персональных данных
15:43 

Система версий

Ri
И тесно облакам.
Как я и предсказывал, начались проблемы с совместимостью. Предлагаю следующую реализацию.

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

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

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

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

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

Для упрощения реализации в качестве версии лучше использовать обычное целое число. Для указания версии API можно выбрать один из следующих способов:

1) Передавать version=42 в качестве одного из GET- или POST-параметров. Этот способ более красивый.

2) В качестве URL для доступа к API использовать www.diary.ru/api/version42/?method=... Я бы предпочел этот способ, так как он более надежный. Не нужно делать общую точку входа для всех версий. Каждая версия будет просто храниться в папке versionN. В таком варианте меньше вероятность, что изменения в коде одной из версий как-то повлияют на остальные версии.

Если запрошенная версия не поддерживается, нужно отдавать клиенту сообщение об этом (во втором варианте реализации достаточно ошибки 404). Если версия не указана, то используется та версия, которая использовалась в момент введения системы версий.

@темы: Тип: Предложение, Статус: не исправлено, Важность: 3 (Major)

Комментарии
2013-09-25 в 09:13 

gluker
очень_очень_очень_много_букв_ без_пробелов
никто и не сомневался что в каком-то виде необходимо сделать поддержку старых клиентов, но выглядеть это будет немного по другому, а именно примерно так:
1. добавляем новый метод version.get - будет возвращать текущую версию апи
2. все изменения и дополнения вносятся в текущую версию вплоть до момента когда количество избыточной информация необходимой для совместимости со старыми версиями не достигнит критического значения, в этот момент будет выпускаться новая версия
3. передавать версию надо будет отдельным необязательным параметром, при этом отсутствие параметра будет означать последную версию
4. основная логика останется неизменной и единой, т.к. она же используется для работы основного и мобильного сайтов, каждый раз копировать ее не целесообразно и на поддержку множества копий нет времени и трудовых ресурсов
----------
это не конечное решение, а лишь направление, когда будет реализован конкретный механизм, он будет описан отдельно

2013-09-25 в 13:50 

Ri
И тесно облакам.
Зачем вообще нужен метод version.get? Когда разработчик делает приложение, он использует конкретную версию API, которая и будет использоваться приложением. Получать версию API динамически нет никакого смысла.

Делать версию необязательным параметром тоже нет смысла. Какой разработчик предпочтет непредсказуемо меняющееся API стабильному?

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

2013-09-26 в 17:42 

gluker
очень_очень_очень_много_букв_ без_пробелов
Зачем вообще нужен метод version.get?
-—-----------
Чтобы разработчик знал под какую версию он сейчас пишет

Делать версию необязательным параметром тоже нет смысла.
------------
Может и так

Еще хочу отметить, что о прекращении поддержки какой-то версии необходимо сообщать заранее (за месяц, например).
-----------
Разработчик будет в отпуске и не получит это уведомление а когда вернется будет уже поздно. Можно сразу определить, что рабочие только последние 2 версии и все.

   

@API

главная