SDK generation

SDK generation — это генерация клиентских библиотек (SDK) для вашего API под нужные языки (JavaScript/TypeScript, Python, PHP, Go и др.): вместо того чтобы каждый интегратор вручную собирал HTTP-запросы, заголовки и парсил ответы, он ставит ваш пакет (npm, pip, composer и т.п.) и вызывает методы как обычные функции — с автодополнением и типами. Генерируем SDK из вашей OpenAPI-спецификации (см. «OpenAPI specs maintenance»), причёсываем результат (понятные имена, примеры, README), настраиваем сборку, версионирование и публикацию в реестры пакетов, а по возможности — автоматическое обновление при совместимых изменениях API (ломающие изменения требуют ревью и новой мажорной версии, а не молчаливого выката). Смысл — снизить порог интеграции: с хорошим SDK партнёр стартует быстрее и делает меньше ошибок. Важно честно: качество SDK — это качество вашей спецификации. Сгенерировать можно из любой спеки, но если она неполная или неточная, SDK унаследует её кривизну — мусор на входе остаётся мусором на выходе; поэтому часть работы — привести спецификацию в порядок (это отдельная услуга, но мы подскажем). Ещё честно: «сгенерировать» — не значит «и забыть». Чистый автоген работает, но бывает «механическим» (неудобные имена, скудные примеры) — поэтому мы его дорабатываем; и при каждом изменении API SDK нужно перегенерировать, протестировать и переопубликовать — это процесс, который мы закладываем. И про языки без иллюзий: каждый язык — это отдельная сборка, тесты и публикация, поэтому делать SDK на пять языков «на всякий случай» дорого и незачем — берём те, на которых реально интегрируются ваши потребители, и поможем выбрать. Если потребитель один и язык один, иногда хватает примеров в документации, а не отдельного SDK — скажем честно. Представьте: партнёр ставит ваш пакет одной командой, пишет client.orders.create(...) с подсказками IDE — и интеграция готова за вечер, а не за неделю. Базовая цена — от 75 000 ₽ за язык: ориентир для API средней сложности и распространённого языка; большой или «раздутый» API, редкий язык и глубокая доработка — дольше и дороже. Зависит от объёма API, числа языков и глубины доработки.

• Каждый интегратор вручную пишет HTTP-запросы к вашему API — долго и с ошибками.
• Партнёры повторяют одну и ту же обвязку (авторизация, ретраи, парсинг) у себя.
• Порог входа высокий — интеграция занимает дни вместо часов.
• При изменении API у потребителей всё ломается, а обновляться трудно.

• Генерация SDK из вашей OpenAPI-спецификации
• Поддержка нужных языков (JS/TS, Python, PHP, Go и др.)
• Доработка: понятные имена методов, типы, примеры, README
• Авторизация, обработка ошибок и ретраи внутри SDK
• Сборка, версионирование и публикация в реестры пакетов (npm, pip…)
• По возможности — автогенерация и обновление при изменении API
• Помощь с выбором языков под реальных потребителей
• Документация по использованию SDK

• Партнёры интегрируются быстрее — пакет вместо ручной обвязки
• Меньше ошибок — авторизация и обработка ответов уже внутри
• Обновления API доходят до потребителей через новые версии SDK
• Ниже порог входа — интеграция за вечер, а не за неделю

• Смотрим спецификацию, выбираем языки под ваших потребителей
• Генерируем SDK, дорабатываем, настраиваем публикацию и версии
• Тестируем на реальных вызовах, публикуем, настраиваем обновление

• SDK ведь генерируется автоматически — зачем платить?

  Сгенерировать каркас из спецификации — да, это автоматизируется, и мы так делаем. Но «сырой» автоген часто неудобен: машинные имена, нет примеров, не настроены ретраи и публикация. Работа — превратить его в библиотеку, которой приятно пользоваться, и поставить процесс обновления. Плюс качество зависит от спецификации: кривая спека — кривой SDK, и это надо привести в порядок.

• На скольких языках делать SDK?

  Только на тех, на которых реально интегрируются ваши потребители. Каждый язык — отдельная сборка, тесты и публикация, поэтому «пять языков на всякий случай» — лишние деньги и поддержка. Часто начинают с одного-двух самых популярных у аудитории; поможем выбрать. Если потребитель и язык один, иногда хватает примеров в документации — скажем честно.

• Что будет при изменении API?

  SDK придётся перегенерировать, протестировать и опубликовать новую версию — иначе он разойдётся с API. Мы по возможности автоматизируем перегенерацию из спецификации и закладываем версионирование. Автообновление безопасно для совместимых изменений; ломающие выпускаем как новую мажорную версию с ревью, а не молча — чтобы у потребителей не ломалось без предупреждения. «Сгенерировал и забыл» с SDK не работает, и мы говорим это сразу.