История одного API: как мы превратили Франкенштейна в красавчика

в 8:39, , рубрики: api, javascript, json, XML, Блог компании Сбербанк, интеграция сервисов, Разработка под e-commerce

Что нужно, чтобы построить экосистему небанковских сервисов, да и вообще любую подобную экосистему? Мастер-система хранения и обработки данных, а также API. В этом посте мы разберем две версии созданного нами API — первую и удачную — и подробно остановимся на том, в чем их важные отличия друг от друга.

История одного API: как мы превратили Франкенштейна в красавчика - 1

Для создания экосистемы небанковских сервисов был выбран наш ключевой платформенный продукт — интернет-банк для корпоративных клиентов Сбербанк Бизнес Онлайн. Соответственно, API для экосистемы небанковских сервисов тоже делали на его основе.

Первую версию API запустили в 2016 году. Создавалась она с оглядкой на другие наши API, по классическим рецептам API крупных финансовых организаций. Вот основные ингредиенты:

  • Протокол SOAP для передачи данных
  • XML-формат
  • Электронная подпись всех запросов
  • Асинхронный режим работы
  • Обязательный hardware-VPN для организации защищенного канала
  • Проприетарная система аутентификации и авторизации
  • Исторически сложившиеся форматы для передачи финансовой информации (например, формат 1С direct banking)

Мы сделали такое решение и начали пилотные интеграции с несколькими неклассическими банковскими сервисами: интернет-магазином «Эвотор», системой управления финансами «Бизнес-аналитика», облачной бухгалтерией «МоеДело» и другими.

Результаты интеграций оказались далеки от желаемых. От API современных нефинансовых сервисов партнеры ждали совсем не того, что принято в области разработки классических банковских продуктов. Хотели получить что-нибудь подобное API современных интернет-гигантов: Facebook, Google, Yandex.

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

Мы проанализировали этот опыт и решили сделать новую версию API с чистого листа. Чтобы получить максимальный win-win со сторонними нефинансовыми сервисами, важнейшие требования изложили заранее:

  • Никаких универсальных и тяжелых форматов, которые учитывают малейшие нюансы. Будем проще!
  • API должен подходить максимально широкому кругу потенциальных партнеров, предлагающих нефинансовые продукты клиентам Сбербанка. Вплоть до внедрения в умные холодильники — с чем черт не шутит.
  • API нужно проектировать с помощью практик и способов, которые используются при создании визуальных интерфейсов. Для этого нужно выявить и проанализировать UX-схемы использования API. Следовать классическим канонам точно не стоит.
  • Нужно избавиться от многотомных описаний, чтобы разработчики могли достичь быстрого результата. С помощью песочницы для тестовых испытаний нужно получать первые положительные результаты уже за час.
  • Максимально отказываемся от проприетарных решений, привязанных к определенной платформе. Все должно быть кроссплатформенным и не ограничивать партнера в используемой инфраструктуре и среде разработки.
  • Партнерам не должно мешать то, чем они не занимаются — сложные структуры данных, механизмы компонентов банковской платформы, особенности работы наших legacy-систем. Скрываем и не забиваем им головы.

С этим списком мы перешли к реализации и выбрали решений для второй версии API:

  • Аутентификация на базе протокола OAUTH 2.0
  • REST-архитектура поверх HTTP без дополнительных сложностей
  • Полностью синхронная работа
  • Формат JSON
  • Опциональное применение электронной подписи — там, где это необходимо
  • Тестовая песочница с развернутым SWAGGER. С помощью этой среды отладки разработчик партнера может смоделировать бизнес-процесс работы и получить результат без написания кода
  • Применение используемого интернет-стартапами подхода Easy Steps при создании документации к API
  • Agile-практики при разработке API — быстрый результат и сбор обратной связи

Что изменилось по факту

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

В первой версии API для авторизации партнеру требовались логин и пароль, сертификат и AccessToken, полученный в результате OAUTH-аутентификации обратившегося клиента:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:upg="http://upg.sbns.zzzzz.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <upg:preLogin>
         <!--Optional:-->
         <upg:userLogin>U1</upg:userLogin>
         <!--Optional:-->
         <upg:changePassword>!d63NvJ+Sa</upg:changePassword>
      </upg:preLogin>
   </soapenv:Body>
</soapenv:Envelope>

В API 2.0 авторизация стала гораздо компактнее. Для доступа к сервисам нужен только AccessToken,  полученный при OAUTH-аутентификации клиента:

{
"access_token": "fdba5482-460c-4535-b829-9fd836fd01f0-1",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "7f545a14-ab7b-45ff-823a-0421e9f3b42e-1",
}

В API 1.0 работа с рублевым платежным поручением также была основана на SOAP:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:upg="http://upg.sbns.zzzzz.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <upg:sendRequestsSRP>
         <!--Zero or more repetitions:-->
         <upg:requests><![CDATA[
        <Request xmlns='http://zzzzz.com/upg/request'
orgId='84b70f22-703f-bf04-db60-bd110572f40d'
requestId='a81ddc6d-fb92-416d-83f9-6785a59a4b17'
version='1.0'
sender='PARTNER'
clientOrgIdHash='ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5'
clientAccessToken='ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5-1'>
<PayDocRuInvoice docExtId='a81decfd-fb92-416d-83f9-6785a59abb65'
orderNum='62' deadLine='2017-04-10T17:16:03'>
<PersonalAcc>40802810000000000000</PersonalAcc>
<AccDoc docDate='2017-02-15' docSum='777' transKind='01' paytKind='01' priority='1'>
<Purpose>!!!!!НДС 18%</Purpose>
</AccDoc>
</PayDocRuInvoice>
</Request>
         ]]></upg:requests>
         <!--Optional:-->
         <upg:sessionId>5a869c00-e979-4280-b11a-6dbbb8a90214</upg:sessionId>
      </upg:sendRequestsSRP>
   </soapenv:Body>
</soapenv:Envelope>

В API 2.0 аналогичным образом все стало гораздо проще и понятнее:

{ 
   "amount": 12.01,  
   "date": "2018-06-22",  
   "deliveryKind": "электронно",  
   "expirationDate": "2018-06-23",  
   "externalId": "1516ec0c-761c-11e8-adc0-fa7ae01bbebc", 
   "operationCode": "01", 
   "orderNumber": "1237",  
   "payeeAccount": "40706810000000000000",  
   "paymentNumber": "1", 
   "priority": "5",  
   "purpose": "Оплата заказа №1237. НДС не облагается.", 
   "urgencyCode": "NORMAL",  
   "vat": { 
     "amount": 100.01,  
     "rate": "7",  
     "type": "NO_VAT"  
}

Электронную подпись мы также облегчили. Вот как все было в API 1.0.

История одного API: как мы превратили Франкенштейна в красавчика - 2
Так выглядел запрос

История одного API: как мы превратили Франкенштейна в красавчика - 3
Вот список атрибутов

История одного API: как мы превратили Франкенштейна в красавчика - 4
И вот готовая подпись

В версии API 2.0 через JSON реализовали все проще:

История одного API: как мы превратили Франкенштейна в красавчика - 5
Сам запрос

История одного API: как мы превратили Франкенштейна в красавчика - 6
Подпись в результате

Итоги

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

Материал подготовил Андрей Хохлов, руководитель проектов в блоке «Корпоративный бизнес» Сбербанка

Автор: Sberbank

Источник


* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js