Понимание платформ на основе API: руководство для менеджеров по продуктам

Чтобы создать цифровой продукт сегодня, нужно интегрировать множество различных бэк-офисных систем с точками взаимодействия с клиентами и устройствами. Стоимость привлечения команды разработчиков программного обеспечения для их объединения в единое рабочее решение может резко возрасти.

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

Примите данные: зачем нам вообще нужны API

Данные о клиентах меняют то, как работает бизнес. При правильном сборе и перемещении они могут помочь компаниям резко увеличить показатели привлечения и удержания клиентов, что в конечном итоге приведет к резкому увеличению доходов.

Но обработка данных — утомительная работа. Вот почему бизнес подключился к компьютерным наукам. В 1990-х годах базы данных, которые автоматизировали самые трудоемкие задачи с данными, стали чрезвычайно популярными в отделах маркетинга. Это привело к кардинальному изменению подхода к маркетинговым стратегиям — этот сдвиг был назван подходом, основанным на данных .

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

Но инженеры-программисты стоят дорого, а их коммуникационный интерфейс требует усилий.

Когда количество каналов сбора данных охватило несколько отделов и даже сторонних компаний, узким местом стали базы данных и их операторы. Предприятиям нужно было найти автоматизированный способ доступа к хранилищам данных.

Так возникла идея систем, ориентированных на API.

Чем на самом деле является API без Tech Lingo

Системы, основанные на API, которые сегодня обычно сокращаются как API ( программируемый интерфейс приложения), представляют собой приложения, которые гарантируют, что другие системы могут получить доступ к своим данным унифицированным и безопасным способом.

Без степени информатики Application Programmable Interface на самом деле не звонит в колокол. Давайте посмотрим на более осязаемое объяснение.

Одна из лучших аналогий, которые я нашел в сети, была написана Тайджей:

«Если вы идете в ресторан в качестве клиента, вам нельзя входить на кухню. Вы должны знать, что доступно. Для этого у вас есть меню. Ознакомившись с меню, вы делаете заказ официанту, который передает его на кухню и доставляет то, что вы просили. Официант может доставить только то, что может предоставить кухня.

Лучшая аналогия API, которую я видел: возьмем ресторан. Меню — это API, ваш заказ — вызов API, еда с кухни — ответ.

— Аарти 發財! (@AarthiD) 19 декабря 2013 г.

Как это связано с API? Официант — это API. Вы тот, кто просит об услуге. Другими словами, вы являетесь клиентом или потребителем API. Меню — это документация, объясняющая, что вы можете запросить у API. Кухня — это, например, сервер; базу данных, которая содержит только определенный тип данных — все, что покупатель купил для ресторана в качестве ингредиентов, что шеф-повар решил предложить и что повара умеют готовить».

Итак, еще раз:

• Кухня
  База данных, никакие клиенты не позволяют защитить целостность данных.
• Официант
  API, посредник, который знает, как обслуживать данные из базы данных, не нарушая ее функционирования.
• Клиент
  Внешняя система, которая хочет получить свои данные
• Меню
  Ссылка на формат данных, которую внешние системы должны использовать для выполнения своей работы.
• Заказ
  Фактический одиночный вызов API.

При нынешнем состоянии технологий разработчику программного обеспечения все еще требуется «сделать заказ». Но это намного быстрее (читай: дешевле), потому что меню, как и в McDonald's, более или менее стандартизировано во всем мире.

Итак, теперь мы наденем обувь разработчика программного обеспечения и попытаемся вызвать образцовый API. Не волнуйтесь; мы не собираемся выходить за рамки школьных уроков информатики.

Как ваше приложение погоды получает данные: основы API

Мы собираемся выяснить, как ваше погодное приложение узнает текущую температуру. Таким образом, мы получим основы того, как общаться с системами через Интернет.

Что нам нужно:

• База данных погоды
• Браузер
• Немного силы воли

Вот и все! Современные технологии позволяют легко тестировать API без использования больших инструментов разработчика.

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

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

Анатомия запроса API

В этой статье мы будем использовать API https://openweathermap.org. Посетите сайт и попробуйте проверить погодные условия в нескольких местах. Надеюсь, сегодня в Катовице вы чувствуете себя лучше меня:

Как вы могли догадаться, веб-сайт вызывает API для получения данных. Разработчики реализовали это таким образом, что каждый раз, когда вы нажимаете поиск , за кадром приложение стучит в дверь API и говорит «дайте мне <город> температуру».

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

1. В Chrome перейдите в Меню → Дополнительные инструменты → Инструменты разработчика;
2. Перейдите на вкладку «Сеть»;
3. Попробуйте проверить температуру в разных городах в виджете выше;
4. В списке внизу вы увидите ссылки, которые были вызваны:
   

   

   
   Если вы скопируете ссылку, вы увидите, что она включает название местоположения и пару других параметров.
   

    https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

5. Когда вы вставляете ссылку в адресную строку браузера, вы должны увидеть ответы API:
   

    jQuery19103887954878001505_1542285819413({"message":"accurate","cod":"200","count":1,"list":[{"id":3096472,"name":"Katowice","coord":{"lat":50.2599,"lon":19.0216},"main":{"temp":281.69,"pressure":1031,"humidity":61,"temp_min":281.15,"temp_max":282.15},"dt":1542285000,"wind":{"speed":3.6,"deg":50},"sys":{"country":"PL"},"rain":null,"snow":null,"clouds":{"all":90},"weather":[{"id":804,"main":"Clouds","description":"overcast clouds","icon":"04d"}]}]})

6. Это немного хаотично, но если вы удалите содержимое круглых скобок и запустите его с форматировщиком данных, вы увидите структуру, которая имеет смысл:
   

    { "message":"accurate", "cod":"200", "count":1, "list":[ { "id":3096472, "name":"Katowice", "coord":{ "lat":50.2599, "lon":19.0216 }, "main":{ "temp":281.69, "pressure":1031, "humidity":61, "temp_min":281.15, "temp_max":282.15 }, "dt":1542285000, "wind":{ "speed":3.6, "deg":50 }, "sys":{ "country":"PL" }, "rain":null, "snow":null, "clouds":{ "all":90 },

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

Слово объяснения того, что мы только что сделали здесь.

Веб-приложение, стоящее за веб-сайтом Open Weather Map, берет данные из API и отображает их на веб-сайте.

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

То же предложение на техническом жаргоне: приложение, стоящее за веб-сайтом, отправляет запрос в конечную точку API, предоставляя в качестве аргумента название города.

Затем API отвечает (отправляет ответ API ) текстовым сообщением в формате JSON .

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

• Город,
• Улица и номер,
• Иногда дополнительная информация о том, как добраться до вашего офиса.

А для подключения к API по аналогии нужно:

• https://openweathermap.org/ (ссылка) Город или root-endpoint — начальная точка, интернет-адрес сервера, к которому вы хотите подключиться, в нашем случае.
• data/2.5/find (ссылка) Номер улицы или путь — определяет ресурс, который вы хотите получить от API.
• ?callback=jQuery19103887954878001505 1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22& =1542285819418 (link) Дополнительная информация или параметры запроса

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

Теперь давайте наденем хакерскую шляпу поплотнее. В нашем случае не все параметры запроса необходимы для получения данных о погоде. Попробуйте удалить другие параметры после вопросительного знака ( ? ) и проверьте, как отвечает Weather API.

Например, вы можете начать с удаления callback из ссылки запроса:

 https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

Результат:

 https://openweathermap.org/data/2.5/find?q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

Если вы поиграете с другими, вы увидите, что некоторые из них также необязательны. На самом деле обязательными являются только q и appid :

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Как узнать, что является обязательным, а что необязательным? Как узнать, где взять корневую конечную точку и путь?

Документация по API: необходимо прочитать перед началом работы

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

В нашем случае документация https://openweathermap.org/current показывает доступные конечные точки. Он также объясняет все поля данных ответа, поэтому вы можете узнать, какую информацию API ответит, еще до того, как вы отправите запрос.

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

Создание вызова API с нуля

Подведем итоги наших выводов. Мы уже отправили запрос в API. Мы выяснили правильную ссылку, обнюхав, что OpenWeatherMap делает за кулисами. Этот подход называется реверс-инжинирингом, и часто он сложен или вообще невозможен.

Более того, в большинстве случаев поставщики API запрещают пользователям чрезмерно использовать эту опцию. Поэтому нам стоит научиться «вызывать» API по правилам (в смысле — документации).

Один из способов сделать это — закодировать его. Но так как мы не кодеры ( пока! ), мы собираемся использовать инструменты, которые сделают это проще. Настолько проще, что даже разработчики программного обеспечения имеют его в своем арсенале.

Как и обещали, не оставим браузер. Но нам нужно установить расширение (только для Chrome) — Postman. Этот простой плагин превращает ваш браузер в коннектор API.

Хорошо, теперь, когда у нас есть инструмент, давайте заглянем в документацию, чтобы узнать, как мы можем получить текущие погодные условия для определенного города с названием https://openweathermap.org/current#name .

В документах говорится, что мы должны использовать следующую конечную точку: api.openweathermap.org/data/2.5/weather?q={city name}

При разборе получаем следующие элементы:

• Корневая конечная точка: api.openweathermap.org
• Путь: data/2.5/weather
• Параметр запроса: q={city name} (это означает, что мы должны заменить фигурные скобки на конкретное название города)

Давайте поместим это в Postman. Процесс сводится к трем простым шагам:

1. Нажмите «Запрос» в верхнем меню.
   

   

2. Назовите свой запрос и укажите название каталога в разделе внизу.

   

3. Вставьте конечную точку API, которую вы хотите вызвать, нажмите «Отправить», и вы должны увидеть ответ API в разделе «Ответ»:

   

Поздравляю! Вы только что успешно позвонили своей ели… подождите секунду! Обратим внимание на ответ API:

Это не JSON, заполненный информацией о погоде, которую мы видели раньше. Что вообще означают 401 и неверный ключ API? Наша документация неверна?

Аутентификация

Вы бы никому не позволили получить доступ к вашей коктейльной стойке без вашего разрешения, не так ли? Точно так же поставщики API также хотят контролировать пользователей своего продукта, чтобы защитить его от злонамеренной активности. Что такое вредоносная активность? Например, отправка множества API-запросов одновременно, что «перегреет» сервер и вызовет простои для других пользователей.

Как вы можете контролировать доступ? Так же, как вы охраняете свои напитки! По ключам — ключи API .

Если вы посетите руководство по началу работы из документации Weather API, вы заметите, как вы можете получить свой ключ. Зарегистрируйтесь сейчас и проверьте свой почтовый ящик.

Итак, теперь вопрос в том, как использовать ключ? Согласно документам, это легко: просто скопируйте и вставьте ключ в конце URL-адреса вашей конечной точки (без фигурных скобок).

 api.openweathermap.org/data/2.5/weather?q=Katowice&appid={your API key}

И снова нажмите отправить. Вот и все, теперь мы можем увидеть ответ API!

Но вы можете получить гораздо больше от API, используя Postman. Готовы стать настоящим хакером API?

Параметры API: получение индивидуальных ответов

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

Параметры запроса — это просто структурированный текст, который вы добавляете по адресу конечной точки по следующему шаблону:

1. Знак вопроса ( ? ) после пути,
2. Имя параметра,
3. Символ равенства ( = ),
4. Значение параметра,
5. Амперсанд ( & ) и другие следуют за пунктами 2-4 (таким образом вы можете добавить столько параметров, сколько хотите).

В качестве примера возьмем наш первый запрос:

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Важное примечание: порядок параметров запроса не имеет значения.

 ?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Вышеприведенное аналогично следующему:

 ?appid=b6907d289e10d714a6e88b30761fae22&q=Katowice

Как уже упоминалось, параметры запроса описаны в документации по API. В следующем отрывке из документации API погоды показано, как получить температуру в различных единицах (британских или метрических):

Попробуйте отправить эти два варианта с помощью Postman, чтобы увидеть разницу в результатах. Не забудьте добавить ключ API в конце адреса конечной точки.

Примечание . Всегда уделяйте некоторое время изучению документации и поиску параметров, которые могут значительно сэкономить вам или вашей команде разработчиков время.

Параметры запроса API: как отправить данные в API

До сих пор мы получали информацию от API. Что, если мы хотим добавить или изменить информацию в базе данных за API? Методы запроса - это ответ.

Давайте еще раз взглянем на Почтальона. Вы могли заметить метку GET в верхнем регистре рядом с адресом конечной точки API. Это представляет один из четырех методов запроса. GET означает, что мы хотим получить что-то от API (спасибо, капитан), и это опция по умолчанию. Какие есть другие варианты?

Все еще сбивает с толку? Перейдем к примерам.

API POST: как создать запись в API

Мы не можем ничего создавать или обновлять с помощью Weather API (поскольку он предназначен только для чтения), поэтому нам нужно найти другой для целей тестирования.

Давайте придумаем еще один бизнес-ориентированный пример. Мы собираемся смоделировать следующий сценарий:

Если идет дождь, создайте купон на скидку «поднимите настроение» для своих клиентов.

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

Отказ от ответственности : я соучредитель Voucherify. Я буду рад ответить на ваши вопросы о разработке и реализации цифровой рекламы и, конечно же, о нашем API .

Мы уже знаем, как их получить из предыдущего примера, поэтому давайте сосредоточимся на создании ваучера:

1. Как мы уже говорили, мы всегда должны начинать с документации.
2. Краткое руководство говорит нам, что нужно получить наш ключ API.
   Примечание . Вместо создания учетной записи вы можете использовать тестовые ключи из краткого руководства — через минуту мы покажем, как это сделать.
3. Теперь давайте узнаем, как создать купон на скидку. В Voucherify такая акция представлена ​​как «ваучер».
4. Из документации вы узнаете, что для создания ваучера необходимо вызвать метод POST для конечной точки /vouchers .
5. Создайте новый запрос в Postman.
6. Измените метод на POST.
   

   

7. Вставьте конечную точку Voucherify https://api.voucherify.io/v1/vouchers/ и нажмите «Отправить».
   

   

8. О, щелк, мы не уполномочены вызывать эту конечную точку. Как вы уже догадались, нам нужно предоставить ключи API.
   
   У Voucherify есть немного другой способ сделать это. Вместо того, чтобы помещать их в качестве параметров запроса, вы должны поместить их в заголовки. Это распространенный подход, потому что проще реализовать и поддерживать ключи таким образом, чем добавлять их в качестве параметров запроса.
   
   Добавьте ключи как на картинке и нажмите Отправить. Обратите внимание, что для Voucherify требуется два ключа. Вот те, которые вы можете использовать для целей этого урока:
   X-App-Id: 8a824b12-0530-4ef4-9479-d9e9b9930176 X-App-Token: 9e322bac-8297-49f7-94c8-07946724bcbc

   

9. Мы получаем еще одно сообщение об ошибке, на этот раз в нем говорится, что полезная нагрузка не может быть пустой.
   

   

   
   Какая к черту полезная нагрузка? Как и в случае с GET, мы хотим получить некоторую информацию, с POST нам нужно что-то отправить, и отправляемое сообщение называется полезной нагрузкой, и обычно это файл JSON.
   
   Теперь Voucherify API жалуется, что мы его не предоставили, а это значит, что он не может создать ваучер, потому что мы не указали, какой тип ваучера он должен создать. И что теперь? Вернемся к документам!
10. Давайте найдем, какая информация нужна этому запросу для успешного выполнения. Мы видим множество вариантов в списке.
    

    

    
    Один параметр (тип) является обязательным, а другой необязательным. Допустим, это будет скидка 20%, доступная для первых 100 клиентов, срок действия которой истекает сегодня. Теперь нам нужно найти параметры, отвечающие за эту функцию скидки, и привести их в формат, понятный для Voucherify API. Как видно из приведенных выше примеров, нотация JSON, которую вы должны использовать, выглядит следующим образом:

     { "type":"DISCOUNT_VOUCHER", "discount":{ "percent_off":20.0, "type":"PERCENT" }, "expiration_date":"2018-12-03T23:59:59Z", "redemption":{ "quantity":100 }

11. Чтобы настроить полезную нагрузку в Postman, вставьте сообщение JSON на вкладку Body. Выберите «необработанный» тип и JSON из списка доступных форматов полезной нагрузки и подтвердите, нажав «Отправить».
    

    

12. Вуаля! Voucherify успешно создал наш купон на скидку 20% (поскольку мы работаем с тестовой учетной записью, все сгенерированные коды начинаются с префикса «voucherify.io-»). Маркетинговая команда теперь может поделиться кодом с покупателями, и Voucherify будет автоматически проверять его всякий раз, когда они приходят в ваш магазин, чтобы выкупить его.
    

    

    
    Но как мы узнаем, что это успешный запрос? Во-первых, мы видим, что Voucherify прислал нам сообщение, которое, согласно их документам, выглядит как правильный ответ API. Во-вторых, Postman отображает статус 200 OK — это означает, что наш запрос выполнен успешно. Почему 200 и каков статус?

Коды состояния API и сообщения об ошибках

Большинство API, с которыми вы когда-либо будете взаимодействовать, будут основаны на HTTP. HTTP — это протокол, который стандартизирует связь между различными клиентскими приложениями и серверами в Интернете.

Одним из ключевых элементов HTTP являются коды состояния. Поняв код состояния, вы (или на самом деле системы, которые вы реализуете) можете сразу сказать, что произошло с вашим запросом. Скорее всего, вы сталкивались с одним из самых популярных кодов состояния, когда вводили неправильную ссылку — 404.

Но их гораздо больше, и конечные пользователи обычно их не видят. Они варьируются от 100+ до 500+. Как правило, числа подчиняются следующим правилам:

• 200+ означает, что запрос выполнен успешно;
• 300+ означает, что запрос перенаправляется на другой URL;
• 400+ означает, что произошла ошибка, исходящая от клиентского приложения;
• 500+ означает, что произошла ошибка, исходящая от сервера.

Если бы вы могли повторить шаги еще раз, вы бы увидели, что Voucherify ответил 401 Unauthorized, когда мы не предоставили ключи API. Или 400 Bad Request, когда не было полезной нагрузки, необходимой для запроса Create Voucher. Наконец, мы получили 200 в качестве токена успешного вызова API.

Если вам интересно, что означают коды состояния HTTP, нет лучшего места, чем HTTP Cats (или, может быть, эта статья).

Резюме

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

Дальнейшее чтение

• «Введение в API электронной коммерции для не-разработчиков», Скотт Бринкер
• «Выйдите за рамки Headless CMS — познакомьтесь с Headless Commerce», Михал Седзелевски, Voucherify
• «Как использовать платформы API-First для ускорения создания веб-сайтов», Михал Седзилевски, Medium
• «Как использовать платформу API-First для подготовки прототипа к производству», Михал Седзилевски, Medium
• «Как использовать облако для более быстрого создания приложений», Михал Седзилевски, Hacker Noon.