🧑🔬 Исследование API внешней системы: инструкция 🧑🔬
Исследование API внешней системы - основной шаг при работе с задачами интеграцию систем.
Поэтому, как только API-документация или её подобие получены, можно начинать аналитику по задаче. До этого задачу стартовать практически нереально.
Ниже моя инструкция по быстрому чтению API-документации внешних систем. В ней я рассказываю, что нужно искать для использования в будущих постановках задач на разработчиков.
----------------------
Инструкция по исследованию API:
◽️1. Оглавление
Найти разделы, в которых потенциально есть информация по следующим пунктам из этой инструкции.
◽️2. Авторизация и аутентификация, ограничения
Все запросы скорее всего будут иметь ограничения по доступу. Важно понять механизм авторизации и описать программистам какие параметры надо будет хранить в конфигурациях, что отправлять в хранилище ключей и подобное.
◽️3. Тестовые доступы, если еще не получили
Нужны для проверки как реально работает API через Postman или другой инструмент, и насколько API соответствует документации.
◽️4. Рекомендации по использованию
Примеры сценариев использования. Это не всегда есть в API-документации. Но если есть, то считайте, что задача почти готова. Предложенный сценарий интеграции надо адаптировать под бизнес-процессы текущего проекта.
◽️5. Список методов, необходимых для реализации ваших интеграционных сценариев
На этапе знакомства с документацией сильно вчитываться не надо. Главное понять, что методов для реализации бизнес-процессов текущего проекта достаточно.
◽️6. Общие требования к обработке ошибок
Коды ответов, структура сообщений, сценарии.
----------------------
Эта инструкция поможет вам понять, что вы получили достаточно информации для работы с задачей на интеграцию с внешней системой 🙌
#ИнтеграцииGA
Исследование API внешней системы - основной шаг при работе с задачами интеграцию систем.
Поэтому, как только API-документация или её подобие получены, можно начинать аналитику по задаче. До этого задачу стартовать практически нереально.
Ниже моя инструкция по быстрому чтению API-документации внешних систем. В ней я рассказываю, что нужно искать для использования в будущих постановках задач на разработчиков.
----------------------
Инструкция по исследованию API:
◽️1. Оглавление
Найти разделы, в которых потенциально есть информация по следующим пунктам из этой инструкции.
◽️2. Авторизация и аутентификация, ограничения
Все запросы скорее всего будут иметь ограничения по доступу. Важно понять механизм авторизации и описать программистам какие параметры надо будет хранить в конфигурациях, что отправлять в хранилище ключей и подобное.
◽️3. Тестовые доступы, если еще не получили
Нужны для проверки как реально работает API через Postman или другой инструмент, и насколько API соответствует документации.
◽️4. Рекомендации по использованию
Примеры сценариев использования. Это не всегда есть в API-документации. Но если есть, то считайте, что задача почти готова. Предложенный сценарий интеграции надо адаптировать под бизнес-процессы текущего проекта.
◽️5. Список методов, необходимых для реализации ваших интеграционных сценариев
На этапе знакомства с документацией сильно вчитываться не надо. Главное понять, что методов для реализации бизнес-процессов текущего проекта достаточно.
◽️6. Общие требования к обработке ошибок
Коды ответов, структура сообщений, сценарии.
----------------------
Эта инструкция поможет вам понять, что вы получили достаточно информации для работы с задачей на интеграцию с внешней системой 🙌
#ИнтеграцииGA
👍15❤11💯4🤔1
🧑🔬 Исследование API: пример для DaData 🧑🔬
В предыдущем посте опубликовала инструкцию по исследованию API-документации. Теперь хочу показать как она работает на практике для проекта #ShipEasyGA.
----------
◽️1. Оглавление
В онлайн-документации DaData сначала показывается общий справочник всех API. В нем нам могут подойти:
🟢 Разбор адреса из строки («стандартизация»)
🟢 Автодополнение при вводе («подсказки»)
🟢 Геокодирование для определения координат адреса, если их не будет в основном API по стандартизации адресов.
Внутри документации по отдельным API есть собственное содержание, под заголовком:
+ Как вызвать
+ Что в ответе
+ Коды качества
+ Примеры
+ Ограничения
+ Стоимость
Так устроено оглавление в DaData. Еще пример подобной структуры: Авито.
◽️2. Авторизация и аутентификация, ограничения
На всех страницах API-документации 🟢, в разделе “Как вызвать”, вы найдете стандарте стандартную фразу:
Часто бывает отдельный раздел “Аутентификация”, “Начало работы” как в Авито, или подобный, где описаны эти требования.
Также обращаю внимание на разделы “Ограничения” и “Стоимость”. Через них можем понять, что API платный, и у нас есть расходы на работу системы, которые нужно согласовывать с бизнесом.
Для платных API всегда важно подумать над алгоритмом работы: про минимизацию количества вызовов за счет хранения части данных у нас (кэширование).
◽️3. Тестовые доступы
Для DaData тестовый доступ отсутствует. Если хочешь пользоваться API, то только боевая площадка.
В таком случае рекомендуется завести два аккаунта: для тестирования и боевой. Но это не всегда удобно. Смотреть по ситуации.
◽️4. Рекомендации по использованию
Смотрим раздел “Как вызвать” в документации DaData, где нам предлагают примеры запросов и ответов. Это максимум, который можем найти для DaData.
Но некоторые системы, особенно платежные, предлагают готовый сценарий интеграции. Посмотрите на пример документации от СберПэй. Осталось адаптировать предложенное под нашу систему.
◽️5. Список методов, необходимых для реализации ваших интеграционных сценариев
В DaData у нас просто три разных страницы 🟢, которые могут подойти. Пока я на этапе первичной аналитики, то считаю, что 3 метода подходят, но надо будет финализировать этот список.
◽️6. Общие требования к обработке ошибок
В DaData дают “Коды ответа на запрос” на отдельных страницах документации 🟢, но не всегда.
В СберПэй подробно расписаны примеры ошибок на каждый запрос.
В некоторых API-документациях есть отдельный раздел в оглавлении с описанием типовых ошибок в API.
А иногда это вообще опускают и не делают. Всякое бывает 😁
----------
На этапе исследования я делаю заметки где-что искать. Если какой-то информации нет, то дозапрашиваю ее у разработчиков или тех.поддержки внешней системы.
👉 Далее перехожу к тестированию API-методов, выделенных в п.5.
Тестирование помогает понять, как работает API и убедиться, что все соответствует документации.
Это нужно, чтобы после передачи задачи в разработку программисты не сталкивались с проблемами неработоспособности внешних систем и задача не вставала.
#ИнтеграцииGA
В предыдущем посте опубликовала инструкцию по исследованию API-документации. Теперь хочу показать как она работает на практике для проекта #ShipEasyGA.
----------
◽️1. Оглавление
В онлайн-документации DaData сначала показывается общий справочник всех API. В нем нам могут подойти:
🟢 Разбор адреса из строки («стандартизация»)
🟢 Автодополнение при вводе («подсказки»)
🟢 Геокодирование для определения координат адреса, если их не будет в основном API по стандартизации адресов.
Внутри документации по отдельным API есть собственное содержание, под заголовком:
+ Как вызвать
+ Что в ответе
+ Коды качества
+ Примеры
+ Ограничения
+ Стоимость
Так устроено оглавление в DaData. Еще пример подобной структуры: Авито.
◽️2. Авторизация и аутентификация, ограничения
На всех страницах API-документации 🟢, в разделе “Как вызвать”, вы найдете стандарте стандартную фразу:
Чтобы вызвать метод, и подтвердите почту.
Часто бывает отдельный раздел “Аутентификация”, “Начало работы” как в Авито, или подобный, где описаны эти требования.
Также обращаю внимание на разделы “Ограничения” и “Стоимость”. Через них можем понять, что API платный, и у нас есть расходы на работу системы, которые нужно согласовывать с бизнесом.
Для платных API всегда важно подумать над алгоритмом работы: про минимизацию количества вызовов за счет хранения части данных у нас (кэширование).
◽️3. Тестовые доступы
Для DaData тестовый доступ отсутствует. Если хочешь пользоваться API, то только боевая площадка.
В таком случае рекомендуется завести два аккаунта: для тестирования и боевой. Но это не всегда удобно. Смотреть по ситуации.
◽️4. Рекомендации по использованию
Смотрим раздел “Как вызвать” в документации DaData, где нам предлагают примеры запросов и ответов. Это максимум, который можем найти для DaData.
Но некоторые системы, особенно платежные, предлагают готовый сценарий интеграции. Посмотрите на пример документации от СберПэй. Осталось адаптировать предложенное под нашу систему.
◽️5. Список методов, необходимых для реализации ваших интеграционных сценариев
В DaData у нас просто три разных страницы 🟢, которые могут подойти. Пока я на этапе первичной аналитики, то считаю, что 3 метода подходят, но надо будет финализировать этот список.
◽️6. Общие требования к обработке ошибок
В DaData дают “Коды ответа на запрос” на отдельных страницах документации 🟢, но не всегда.
В СберПэй подробно расписаны примеры ошибок на каждый запрос.
В некоторых API-документациях есть отдельный раздел в оглавлении с описанием типовых ошибок в API.
А иногда это вообще опускают и не делают. Всякое бывает 😁
----------
На этапе исследования я делаю заметки где-что искать. Если какой-то информации нет, то дозапрашиваю ее у разработчиков или тех.поддержки внешней системы.
👉 Далее перехожу к тестированию API-методов, выделенных в п.5.
Тестирование помогает понять, как работает API и убедиться, что все соответствует документации.
Это нужно, чтобы после передачи задачи в разработку программисты не сталкивались с проблемами неработоспособности внешних систем и задача не вставала.
#ИнтеграцииGA
DaData.ru
API сервиса DaData
Открывает программный доступ к функциям «Дадаты».
Поможет встроить сервис куда угодно: в сайт, мобильное приложение,
CRM, продукты «1С» — DaData API.
Поможет встроить сервис куда угодно: в сайт, мобильное приложение,
CRM, продукты «1С» — DaData API.
👍11❤5
🟢🟠🟡 Инструменты системного аналитика для тестирования в API 🟢🟠🟡
Проверка API — важная часть работы системного аналитика, особенно при интеграции систем и сервисов, при работе в Backend-команде.
Не всегда API-документация актуальна и отражает все сценарии работы, которые будут использованы в интеграции. Особенно это касается поведения внешней системы при ошибках.
👉 Системному аналитику необходимо убедиться, что API внешней системы будет работать именно так, как описано в документации (если она есть, а если нет - то составить), чтобы затем предоставить информацию разработчикам.
Проверка API внешних систем помогает выявить проблемы в работе внешних систем на ранних стадиях разработки, несоответствия документации реальности, а также проверить полноту данных и доступность сервисов в целом.
Также этап тестирования помогает понимать работу API, чтобы грамотно описывать интеграционные сценарии.
Список инструментов, которые помогают системным аналитикам в тестировании API:
🟠 Postman
🟡 SoapUI
🟣 Insomnia
🟢 Swagger
Подробности в картинках к посту ☝️
#ИнтеграцииGA
Проверка API — важная часть работы системного аналитика, особенно при интеграции систем и сервисов, при работе в Backend-команде.
Не всегда API-документация актуальна и отражает все сценарии работы, которые будут использованы в интеграции. Особенно это касается поведения внешней системы при ошибках.
👉 Системному аналитику необходимо убедиться, что API внешней системы будет работать именно так, как описано в документации (если она есть, а если нет - то составить), чтобы затем предоставить информацию разработчикам.
Проверка API внешних систем помогает выявить проблемы в работе внешних систем на ранних стадиях разработки, несоответствия документации реальности, а также проверить полноту данных и доступность сервисов в целом.
Также этап тестирования помогает понимать работу API, чтобы грамотно описывать интеграционные сценарии.
Список инструментов, которые помогают системным аналитикам в тестировании API:
🟠 Postman
🟡 SoapUI
🟣 Insomnia
🟢 Swagger
Подробности в картинках к посту ☝️
#ИнтеграцииGA
🔥24👍15❤7
GetAnalyst_Postman_Практическое_руководство_с_примером_DaData.pdf
9.5 MB
🔥 Новое практическое руководство по Postman - с нуля до результатов 🔥
Один из первых и основных шагов при работе систеных аналитиков с задачами на интеграции — проверка API внешней системы.
Основной инструмент для тестирования и документирования API: Postman.
Если вы еще не использовали его в работе, хотите освоить или получить дополнительную практику, то я подготовила подробную инструкцию с картинками для вас 🧡
В ней вы найдете следующие API DaData:
▫️ Разбор адреса из строки («стандартизация»)
▫️ Автодополнение при вводе («подсказки»)
▫️ Геокодирование
Эти методы нужно было исследовать для работы с интеграционной задачей на структурирование адреса в проекте #ShipEasyGA.
Больше всех подходит "Автодополнение при вводе («подсказки»)". Его и будем использовать для дальнейшей работы 🙂
#ИнтеграцииGA
Один из первых и основных шагов при работе систеных аналитиков с задачами на интеграции — проверка API внешней системы.
Основной инструмент для тестирования и документирования API: Postman.
Если вы еще не использовали его в работе, хотите освоить или получить дополнительную практику, то я подготовила подробную инструкцию с картинками для вас 🧡
В ней вы найдете следующие API DaData:
▫️ Разбор адреса из строки («стандартизация»)
▫️ Автодополнение при вводе («подсказки»)
▫️ Геокодирование
Эти методы нужно было исследовать для работы с интеграционной задачей на структурирование адреса в проекте #ShipEasyGA.
Больше всех подходит "Автодополнение при вводе («подсказки»)". Его и будем использовать для дальнейшей работы 🙂
#ИнтеграцииGA
❤33🔥18❤🔥6👍6
👉 Пример интеграционного Use Case - технические детали в задачах на интеграции 👉
В одном из предыдущих постов я показала пример Use Case заполнения адреса с использованием внешней системы DaData, без технических деталей. Его пока нельзя передавать в разработку, так как в нем отсутствуют требования к вызываемым методам API внешних систем.
Вопрос, на который я хочу ответить в этом посте:
1. В интеграционных сценариях прописывают вызовы API-методов нашего Backend и API внешней системы.
2. Есть обработка ошибок, связанная с проблемами на стороне внешней системы (в том числе ее недоступность, длительное ожидание ответов от нее).
Для полной постановки задачи нужно будет также сделать:
- Описать маппинг данных: БД, наш UI, наш API, API внешней системы.
- Выделить задачи для Frontend и Backend разработчиков.
В картинках к посту выделила места в Use Case, которые добавила после исследования API внешней системы через Postman☝️☝️☝️
#ИнтеграцииGA
В одном из предыдущих постов я показала пример Use Case заполнения адреса с использованием внешней системы DaData, без технических деталей. Его пока нельзя передавать в разработку, так как в нем отсутствуют требования к вызываемым методам API внешних систем.
Вопрос, на который я хочу ответить в этом посте:
Чем отличается обычный Use Case от интеграционного?
1. В интеграционных сценариях прописывают вызовы API-методов нашего Backend и API внешней системы.
2. Есть обработка ошибок, связанная с проблемами на стороне внешней системы (в том числе ее недоступность, длительное ожидание ответов от нее).
Для полной постановки задачи нужно будет также сделать:
- Описать маппинг данных: БД, наш UI, наш API, API внешней системы.
- Выделить задачи для Frontend и Backend разработчиков.
В картинках к посту выделила места в Use Case, которые добавила после исследования API внешней системы через Postman☝️☝️☝️
#ИнтеграцииGA
❤32👍7❤🔥3👎2