[Анализ и проектирование систем, Интерфейсы, API] Проектирование интеграции с веб-сервисом

Ответить на тему

Автор

Сообщение

news_bot ^®

Стаж: 6 лет 9 месяцев
Сообщений: 27286

news_bot ^® написал(а)
29-Июн-2021 21:33

Цитировать

Все больше и больше аналитиков, проджектов и продактов приходят в айти из маркетинга, консалтинга, продаж и других нетехнических индустрий, да и вообще без опыта работы. И я тут не стал исключением. Существует проблема, что в первые годы на тебя падает немерено технических терминов и концепций, ты пытаешься в них разобраться, но не понимаешь до какого уровня деталей тебе надо опускаться в каждой из них. Надо ли разбираться, что значит обнаруженный тобой термин WSDL и какие бывают виды асинхронного выполнения запроса, или достаточно знать, что у веб-сервиса просто есть запрос и ответ? Статья нужна, чтобы решить эту проблему для одной из самых частых фичей – научиться работать с веб-сервисом для обмена данными, выполнения целевых действий в других системах и прочих интеграций.На русском и английском есть куча материала про то, зачем нужны веб-сервисы, какие они бывают, как их спроектировать, есть прикольные кейсы. Но про то, как взаимодействовать с ними на практике, особенно на сложных корпоративных системах, я не нашел ничего исчерпывающего. А как показывает опыт, черт кроется именно в деталях и подпунктах, большинство из описанных в этой статье – мои собственные «шишки».Представь, что тебе надо сделать такую штуку: в зависимости от ответа веб-сервиса, который угадывает зарплату человека, отобразить пользователю кнопку разного цвета. Скажем если зарплата до 20 тыс. рублей, ты делаешь красную кнопку, если от 20 до 100 тыс., то желтую, и если она больше 100 тыс., то зеленую. Казалось бы, что может быть проще! Но чтобы описать эту задачу для разработки и разобраться во всем самому, тебе будет не лишним обратить внимание на 15 разных вопросов, а если фича безумно важная, то еще на 8 других.Ну чего, погнали, программа минимум:

Найди или попроси страницы с описанием веб-сервиса и задачи, в которых кто-то описывал интеграцию с ним. Проверь наличие всех пунктов ниже, чтобы не раздражать человека, спрашивая лишний раз :)
Продовые и тестовые ссылки / адреса (англ. Endpoints PROD, QA / TEST). Веб-сервис доступен именно по этим адресам. Ссылка на тестовый контур также будет полезна, если на проде проверить работу сервиса нельзя – к примеру если он вносит непоправимые изменения. Ссылки очень похожи на адреса обычных сайтов по формату, часто в них будет содержаться слово “api”. Можно попробовать открыть их в браузере, и иногда что-то отобразится.
Тут веб-сервис поиска в Youtube выдал ошибку, поскольку ожидал, что в запросе мы передадим ключ API (выдается на их сайте, индивидуальный для каждого)
Аутентификация. Как мы будем авторизоваться в веб-сервисе, чтобы он нам отдал нужные данные? Тут много разных вариантов: по ключу API, токену, логину и паролю в теле запроса, бывают и другие.
Запроси WSDL, если это SOAP веб-сервис. Есть два самых популярных видов веб-сервисов: SOAP и REST, обычно об этом написано в самом верху страницы с описанием сервиса. REST теоретически может поменять формат ответа в любой момент, а SOAP отвечает только в формате, который находится в схеме (XSD – XML Schema Definition). Эта схема ответа, а также ссылки содержатся в файле WSDL, который ты передаешь с запросом – то есть для SOAP ссылки можно отдельно не запрашивать, если уже есть WSDL. Соответственно на продовом и тестовом контурах WSDL разные, потому что содержат разные адреса. Также для SOAP придется делать запросы в какой-то программе, часто пользуются бесплатным SOAP UI. SOAP для запросов и ответов использует .XML файлы, а REST - .JSON, .XML, .TXT
Примеры запросов: что передавать в веб-сервис для разных случаев, чтобы получить нужные тебе данные? Все ли эти данные у тебя есть?
Запрос в Swagger
Запроси примеры релевантных успешных ответов. Если ты имеешь дело с REST, то еще часто для описания сервисов делают Swagger (файлик для приложения SwaggerUI). Попроси ссылку на него - там есть приятный интерфейс, можно отправить запрос - получить ответ, авторизоваться, посмотреть какие есть соседние с твоим сервисы на PROD и QA.
Ответ в Swagger
Что мы делаем во время ожидания ответа от сервиса? Особенно актуально, если имеем дело с сервисами, которые долго отвечают, и это заставляет ждать живого пользователя, как в примере с разноцветной кнопкой. Пользователь может не понять, почему ничего не происходит.
Таймаут (максимальное время ожидания ответа) и реакция на него. После таймаута мы перестаем ожидать ответ и происходит определенное поведение твоей системы, к примеру отправка запроса в другой сервис. Почему перестаем ожидать ответ: либо из-за того, что не можем больше ждать, надо уже как-то реагировать, либо если спешить некуда, но мы достаточно уверены, что сервис уже не ответит. Будет круто, если сможешь получить распределение времени ответа сервиса. Можно будет поставить таймаут, к примеру, как 99 перцентиль, но чаще это уже будет описано / можно спросить разработчиков сервиса.
Характеристики полей: тип поля, обязательность и длина строки.
- Тип поля. Надо следить, чтобы мы передавали в запросе поля в том же формате, который ожидает получить сервис. Самые частые кейсы тут: передаем число как строку текста “2007”, вместо 2007 и разные форматы дат и времени, к примеру Date “2007-01-01” вместо DateTime “2007-01-01 11:00:00”. Когда получаем ответ от сервиса, тоже лучше следить, что данные из ответа запроса приходят в том же типе/формате, который мы ожидаем, иначе их надо будет конвертировать (переводить) в нужный тип.
- Обязательность полей – есть поля, без которых запрос не будет работать, а есть те, которые можно не передавать иногда. Если ты знаешь, что поле необязательное, но тебе его надо передавать по полученному примеру запроса, то можно обсудить с разработчиками сервиса, что будет если не передавать его, возможно оно лишнее и не надо его добывать откуда-то, чтобы положить в запрос. Для SOAP можно посмотреть обязательность полей в WSDL или в примере запроса, ищи зеленый текст <! -- Optional: -->. Для REST это можно посмотреть в Swagger, обозначается красной звездочкой.
  SOAP UI
  Swagger
- Длина строк – лучше проверить, что строки текста, которые мы передаем в запросе не сожмутся. Для SOAP есть возможность посмотреть в WSDL мин / макс длину строк в символах, ищи поля minLenght / maxLength. Для REST это обычно само собой подразумевается, но если ты делаешь нереально важную фичу и передаешь текстовую строку длиной в абзац в поле, которое по смыслу должно быть коротким (Имя, Телефон, Адрес), лучше уточнить это у разработчиков сервиса.
Поведение твоей системы в случае ошибок от сервиса (англ. exception flow). Надо продумать, как реагировать на ошибки от сервиса, к примеру можно делать перезапросы по такому правилу: сервис запрашивается раз в 20 минут, суммарно до 10 раз, после чего забиваем.
Поведение твоей системы, если важные поля в ответе придут пустыми / с некорректным значением (к примеру, писать сообщение об этом). На практике такое случается частенько, пример: сервис начинает возвращать не валидированные данные из новых источников.
Полностью проверь работу интеграции на PROD / QA контуре, если есть такая возможность. Обрати внимание, что на QA контуре часто бывают моки или заглушки – когда сервис возвращает в ответе одно и то же подстановочное значение вместо нормальной обработки запроса. Если веб-сервис должен что-то сделать в другой системе, проверь, что это целевое действие выполнено, покажи запросы владельцу сервиса. На практике довольно часто всплывают проблемы именно на этом этапе.
Нагрузка. Обсуди с владельцем сервиса частотность вызова его сервиса, изменение нагрузки в течение суток / недели, а также ее потенциальные изменения в будущем.
Делать ли логирование запроса и ответа. Есть много плюсов: можно отслеживать баги, фрод, смотреть сколько было запросов сервиса суммарно.
интерфейс для просмотра логов Kibana
Кэширование ответа сервиса. Если есть вероятность, что в течение короткого времени потребуется вызов сервиса с такими же параметрами запроса и предполагается, что ответ не будет меняться, то можно этот ответ сохранить, чтобы не вызывать сервис еще раз. Особенно актуально, если вызов сервиса является небесплатным и небыстрым. REST можно кэшировать, используя HTTP протокол – более быстрый вариант для разработки, а SOAP – только если отдельно на своей системе сохранять данные.

Левел 2. Эти моменты лучше проверить, если фича важная:

Доступность сервиса в зависимости от времени. Если у сервиса есть “часы пик” во время которых он становится менее доступным, следует это учесть во время планирования работы с ним: предупредить пользователей, внимательно продумать реакцию на таймаут и ошибки в ответах.
Алерты. Если успешный ответ от сервиса является критичным, можно настроить алерты на ошибки, доступность или резкое изменение среднего значения в ответе / доли определенных значений.
Надо ли реализовать логику обработки ответа на стороне веб-сервиса. На нашем примере с разноцветной кнопкой в зависимости от полученной в ответе зарплаты: можно сделать эту логику в твоей системе (часто самый простой вариант), однако если границы 20 и 100 тыс. предполагается часто менять, а также классификацией красный / желтый / зеленый будут пользоваться другие люди и системы, может иметь смысл доработать сервис и передавать в ответе сразу цвет кнопки. Иначе запросто может возникнуть рассинхронизация и одинаковые по зарплате люди будут с разными кнопками.
Меняется ли структура ответа в зависимости от параметров запроса? К примеру, в запросе есть параметр “strategy”, в зависимости от которого в ответе возвращается разное число параметров. Наша система должна учитывать это.
Контракт. Если ты меняешь существующую интеграцию с веб-сервисом, не забудь о том, что на вашей системе может быть контракт с ним (считываем из ответа только определенные в контракте поля) и может потребоваться его изменить.

Левел 3. Самый важный проект за год, баги недопустимы!

Примеры ошибок. Возможно, потребуются сценарии и алерты на разные ошибки. Так ошибки описаны у Яндекс.Толоки
Невыполнение целевого действия при успешных ответах. Бывают случаи, когда сервис в случае невыполнения целевого действия возвращает 200 OK (код об успешном выполнении). Пример: сервис сам передает запрос в другой сервис после нашего запроса, но не дожидается ответа от него и сразу шлет 200 OK, но на самом деле целевое действие еще могло не успеть произойти и должен быть ответ с кодом 201 Created.
Синхронное / Асинхронное выполнение запроса. При Синхронном выполнении запроса, он обрабатывается сразу при получении. При асинхронном взаимодействии запросы попадают в очередь на стороне сервиса и целевое действие сразу не выполняется. У владельцев или пользователей сервиса можно узнать, сколько в среднем событие лежит в очереди и сколько еще требуется времени на выполнение целевого действия. Аналогия – ты сидишь в очереди в клинике; время, когда ты будешь свободен – это время ожидании в очереди плюс консультации у врача.
Самые популярные HTTP статус коды

Спасибо за внимание! Делитесь в комментах своими кейсами.
Кирилл Марк, Тинькофф
@mar_kirr
===========
Источник:
habr.com
===========
Похожие новости:

Теги для поиска: #_analiz_i_proektirovanie_sistem (Анализ и проектирование систем), #_interfejsy (Интерфейсы), #_api, #_vebservisy (веб-сервисы), #_soap, #_rest, #_api, #_wsdl, #_interfejsy (интерфейсы), #_vzaimodejstvie_sistem (взаимодействие систем), #_analiz_i_proektirovanie_sistem (
Анализ и проектирование систем
), #_interfejsy (
Интерфейсы
), #_api

Профиль ЛС

Ответить на тему

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 22-Ноя 11:10
Часовой пояс: UTC + 5