Все больше и больше аналитиков, проджектов и продактов приходят в айти из маркетинга, консалтинга, продаж и других нетехнических индустрий, да и вообще без опыта работы. И я тут не стал исключением. Существует проблема, что в первые годы на тебя падает немерено технических терминов и концепций, ты пытаешься в них разобраться, но не понимаешь до какого уровня деталей тебе надо опускаться в каждой из них. Надо ли разбираться, что значит обнаруженный тобой термин 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 Кэширование ответа сервиса. Если есть вероятность, что в течение короткого времени потребуется вызов сервиса с такими же параметрами запроса и предполагается, что ответ не будет меняться, то можно этот ответ сохранить, чтобы не вызывать сервис еще раз. Особенно актуально, если вызов сервиса является небесплатным и небыстрым.
Левел 2. Эти моменты лучше проверить, если фича важная:
Доступность сервиса в зависимости от времени. Если у сервиса есть “часы пик” во время которых он становится менее доступным, следует это учесть во время планирования работы с ним: предупредить пользователей, внимательно продумать реакцию на таймаут и ошибки в ответах.
Алерты. Если успешный ответ от сервиса является критичным, можно настроить алерты на ошибки, доступность или резкое изменение среднего значения в ответе / доли определенных значений.
Надо ли реализовать логику обработки ответа на стороне веб-сервиса. На нашем примере с разноцветной кнопкой в зависимости от полученной в ответе зарплаты: можно сделать эту логику в твоей системе (часто самый простой вариант), однако если границы 20 и 100 тыс. предполагается часто менять, а также классификацией красный / желтый / зеленый будут пользоваться другие люди и системы, может иметь смысл доработать сервис и передавать в ответе сразу цвет кнопки. Иначе запросто может возникнуть рассинхронизация и одинаковые по зарплате люди будут с разными кнопками.
Меняется ли структура ответа в зависимости от параметров запроса? К примеру, в запросе есть параметр “strategy”, в зависимости от которого в ответе возвращается разное число параметров. Наша система должна учитывать это.
Логика обработки ответа. Если ты меняешь существующую интеграцию с веб-сервисом, не забудь о том, что на вашей системе может быть логика, которую надо обновить. К примеру, вы считываете только определенные поля из ответа и надо добавить новые.
Левел 3. Самый важный проект за год, баги недопустимы!
Примеры ошибок. Возможно, потребуются сценарии и алерты на разные ошибки. Так ошибки описаны у Яндекс.Толоки
Невыполнение целевого действия при успешных ответах. Бывают случаи, когда сервис в случае невыполнения целевого действия возвращает 200 OK (код об успешном выполнении). Пример: сервис сам передает запрос в другой сервис после нашего запроса, но не дожидается ответа от него и сразу шлет 200 OK, но на самом деле целевое действие еще могло не успеть произойти и должен быть ответ с кодом 201 Created.
Синхронное / Асинхронное выполнение запроса. При Синхронном выполнении запроса, он обрабатывается сразу при получении. При асинхронном взаимодействии запросы попадают в очередь на стороне сервиса и целевое действие сразу не выполняется. У владельцев или пользователей сервиса можно узнать, сколько в среднем событие лежит в очереди и сколько еще требуется времени на обработку запроса. Успешные коды 201 и 202 намекают на асинхронность. Если ты их получил, лучше проверить, что целевое действие выполнится.
Самые популярные HTTP статус коды
Спасибо за внимание! Делитесь в комментах своими кейсами.
Кирилл Марк, Тинькофф
@mar_kirr