Как правильно разрабатывать API с поддержкой обратной совместимости. Семинар в Яндексе

Ребята, вы как всегда вовремя! Как раз собирался писать API.

Поделитесь, пожалуйста, ссылочкой на доклад Марата про проектирование систем, о котором в начале видео говорится. Ссылка из доклада (http://study.yandex-team.ru/events/kmb-2/techno/talks/901) наружу не доступна.

очень странно выглдит совет использовать события — это требует глобального/встраевоемого везде медежера событий с интерфейсовм set/get event data, формат которых не задан через интерфейсы

Спасибо за труд!

Хотелось бы больше информации по п. 7: как именно вы поддерживаете версионность тестов относительно версий API, какие лучшие практики совместного рефакторинга самой функциональности API и соответствующих тестов, как лучше анализировать необычное поведение устаревших версий API, когда приходится идти на компромиссы в данных — добавлять фейковую информацию, т.к. новейшее API становится в некоторых процессах уже несовместимым со старым.
Например, в старой версии были ± лайки, в новой решили сделать только лайк, а дислайк в обязательной форме указания причины дислайка. Что в этом случае было бы по вашим процессам создания/поддержки API и тестов со старым функционалом дислайков? Это просто пример, когда со временем развитие API приводит к несовместимостям в логике. Часто в таких случаях применяют разделение на большие ветки версий 1.0/2.0, интересно было бы услышать сталкивались ли вы с таким в процессе развития и какие решения принимались и на основе чего для разрешения подобных задач.

> как именно вы поддерживаете версионность тестов относительно версий API

У наших тестировщиков, например, подняты стенды, которые сравнивают результаты тестов текущей версии с предыдущими (в т.ч. с продакшеном).

> какие лучшие практики совместного рефакторинга самой функциональности API и соответствующих тестов

Эта тема тянет, как минимум, на пару таких семинаров, но, на самом деле, при правильно определённых интерфейсах можно рефакторить как угодно. Проблемы, как правило, не в самом рефакторинге — а в том, что интерфейс был изначально недоопределён или ошибочен.

> как лучше анализировать необычное поведение устаревших версий API

Не понял вопроса.

> Например, в старой версии были ± лайки, в новой решили сделать только лайк, а дислайк в обязательной форме указания причины дислайка.

Это эффективный слом обратной совместимости. Прятать его за какие-то фейковые фасады = гримировать труп.

> Часто в таких случаях применяют разделение на большие ветки версий 1.0/2.0, интересно было бы услышать сталкивались ли вы с таким в процессе развития и какие решения принимались и на основе чего для разрешения подобных задач.

В данный момент мы поддерживаем одновременно четыре мажорных версии АПИ, и пока не планируем сворачивать поддержку старых версий.

Наше соглашение примерно следующее: должны поддерживаться (= исправляться любые критические ошибки) не менее двух последних мажорных версий; развивается при этом (добавляется новый функционал) только последняя мажорная; должен быть прямой доступ как минимум к двум минорным версиям в рамках актуальной мажорной.

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

.

Был доклад на YaC по схожим вопросам.

Как-то работал с очередями сообщении. Если быть точнее — IBM WebSphere MQ.
Вот где поддержка старых версии идет как нигде и никогда.
Например, в оттранслированном заголовочном файле из С в Паскаль:

(****************************************************************)
(*  MQCNO Structure -- Connect Options                          *)
(****************************************************************)

type
  MQCNO = record
    StrucId            : MQCHAR4  ;(* Structure identifier *)
    Version            : MQLONG   ;(* Structure version number *)
    Options            : MQLONG   ;(* Options that control the action of MQCONNX *)
    (* Ver:1 *)
    ClientConnOffset   : MQLONG   ;(* Offset of MQCD structure for client connection *)
    ClientConnPtr      : MQPTR    ;(* Address of MQCD structure for client connection *)
    (* Ver:2 *)
    ConnTag            : MQBYTE128;(* Queue-manager connection tag *)
    (* Ver:3 *)
    SSLConfigPtr       : PMQSCO   ;(* Address of MQSCO structure for client connection *)
    SSLConfigOffset    : MQLONG   ;(* Offset of MQSCO structure for client connection *)
    (* Ver:4 *)
    ConnectionId       : MQBYTE24 ;(* Unique Connection Identifier *)
    SecurityParmsOffset: MQLONG   ;(* Offset of MQCSP structure *)
    SecurityParmsPtr   : PMQCSP   ;(* Address of MQCSP structure *)
    (* Ver:5 *)
  end;
  PMQCNO  = ^MQCNO;
  PPMQCNO = ^PMQCNO;