Проектирование SDK поверх HTTP API

Цель

Поставить клиентскую библиотеку, с которой интегратор — человек или агент — использует API без изучения деталей HTTP, при этом семантика API остаётся явной, а SDK не превращается во второй API, требующий отдельной поддержки.

Предварительные условия

Машиночитаемое описание API, OpenAPI или protobuf, служащее единственным достоверным источником; политика версионирования API; решение о языках, поддерживаемых в первую очередь, с учётом аудитории интеграторов.

Порядок действий

1. Генерируйте транспортный слой — модели, сериализацию и вызовы конечных точек — из описания. Не поддерживайте вручную то, что описание уже определяет. Размещайте сгенерированный код в отдельном пакете или каталоге, чтобы повторная генерация не уничтожала рукописный код.
2. Добавьте единый клиентский объект, владеющий конфигурацией: базовым URL, учётными данными, тайм-аутами, политикой повторов и значением User-Agent с версией SDK. Сначала читайте учётные данные из параметров, затем из переменных окружения; не вводите собственные файлы конфигурации.
3. Преобразуйте ошибки HTTP в один тип исключения или результата, содержащий статус, тело ошибки API, идентификатор запроса и признак допустимости повтора. Не выбрасывайте разные типы для разных конечных точек.
4. Реализуйте повторы один раз, в транспортном слое: только для идемпотентных вызовов или вызовов с ключом идемпотентности, созданным SDK. Используйте экспоненциальное увеличение задержки со случайным разбросом, соблюдайте Retry-After и ограничивайте общее время.
5. Представьте постраничное получение как итератор, загружающий страницы по мере необходимости, и оставьте доступ к непосредственному вызову страницы для клиентов, которым нужен контроль.
6. Для длительных операций предоставьте помощник ожидания, выполняющий опрос по подсказкам сервера и с конечным сроком; он должен возвращать результат либо ошибку операции.
7. Версионируйте SDK независимо от API по правилам семантического версионирования. Основная версия SDK меняется при нарушении совместимости его собственного интерфейса, а не при добавлении поля в API.
8. Проверяйте SDK на сервере с записанными ответами или в тестовой среде в CI, а по расписанию — в работающей тестовой среде. Публикуйте журнал изменений с указанием версии API, на которую рассчитан каждый выпуск SDK.
9. Сделайте README руководством по первому вызову: установка, настройка, один вызов, обработка одной ошибки; для остального давайте ссылки на справочник API.

Ожидаемый результат

Интеграторы пишут меньше кода и реже сталкиваются с ошибками повторов и постраничного получения. Поведение SDK соответствует документированной семантике API, поскольку большая его часть сгенерирована.

Ограничения и основание проверки

Предлагаемый порядок работы; сравнение разных проектов SDK не заявляется. Рукописные средства удобства — строители объектов и помощники, объединяющие несколько вызовов, — чаще всего отдаляют SDK от API. Делайте их тонкими и обозначайте в документации как вспомогательные средства.