🧑🔬 Исследование 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