Технические знания ДЛЯ пРОДАКТА

Что продакт менеджер должен знать об API?

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

Введение
Так же, как вы можете физически сходить в магазин и купить продукты или футболку (вместо того, чтобы производить их самим), сервисы вашего продукта могут «сходить» в один из «магазинов API» и получить прогноз погоды с помощью WeatherAPI, перевод через Google Translate API, мем из MemeAPI (мы его используем чуть позже сегодня) и даже… ответ ChatGPT через OpenAI API.

Чтобы воспользоваться тысячами доступных API, продакт-менеджеру нужно понимать основы структуры API: "эндпоинт" (endpoint), входные данные (input или request) и выходные данные (output или response).

Ниже - 4 примера API, от простого к более сложным, а один из них вы вызовете сами! Поехали.
Пример #1: покупка кофе в виде вызова API
Вызов API — это способ попросить систему выполнить за нас работу. Мы даем что-то на входе (input) и получаем ответ (output) на выходе. При этом нам совершенно все равно, что именно система делает для получения результатов — в этом вся суть.

Например, когда вы заказываете кофе, то обмениваете деньги и выбор кофе — входные данные на чашку кофе — выходные данные. Вы не фокусируетесь на том, как кофе был доставлен из сортировочного центра и на какую полку он был помещен в хранилище. Но вас точно волнует наличие (и качество) результата в вашей чашке кофе.

Вот как может выглядеть документация API для покупки кофе:
# Входные данные (Input):
  • Coffee type: "Латте", "Черный", "Капучино"
  • Milk choice: "Нет", "Обычное", "Кокосовое", "Овсяное"
  • Payment type: "карта", "наличные"

# Выходные данные (Output):
  • Coffee cup
  • Exchange (сдача): если оплата была наличными

# Возможные ошибки (Potential errors):
  • Выбор молока недоступен (например, овсяного молока нет)
  • Мы потеряли ваш заказ (например, бумажка с вашим именем упала на пол)
  • Кофе слишком холодный (например, бариста забыл подогреть молоко)
  • Нет сдачи (например, нет возможности купить кофе по цене 3,75$ за 100$ купюру)
Обратите внимание, что это простое упражнение уже заставило нас рассмотреть «контракт» между клиентом (API client) и поставщиком услуг (service provider) — которые в данном случае является покупателем кофе и кофейней. Теперь мы ясно видим минимальные требования со стороны сервиса для выполнения своей работы (им нужно знать тип кофе, тип молока и получить оплату).

Теперь продакт может развивать эту структуру, например, введя параметр "добавок" (extras):
# Входные данные (Input):
  • Coffee type: "Латте", "Черный", "Капучино"
  • Milk choice: "Нет", "Обычное", "Кокосовое", "Овсяное"
  • Payment type: "карта", "наличные"
  • Extras: "Сироп", "Крем", "Мороженое"
Или, может быть, позже продакт с командой смогут добавить экологичный вариант «в мою кружку», который сэкономит покупателю 40 центов:
# Input Parameters:
  • Coffee type: "Латте", "Черный", "Капучино"
  • Milk choice: "Нет", "Обычное", "Кокосовое", "Овсяное"
  • Payment type: "карта", "наличные"
  • Extras: "Сироп", "Крем", "Мороженое"
  • In-my-cup: "да / нет" (уменьшает цену на 40 центов)
Почему это полезно продакту?
Магия в том, что мы перешли от абстрактного «покупка кофе» к очень четкому набору правил: что даем, что получаем обратно и что может пойти не так. Это позволяет продакту очень предметно общаться со стейкхолдерами. Например:

  • Отдел поставок может просмотреть на API контракт и сказать, что у них нет овсяного молока, а вместо него есть соевое.
  • Финансовый отдел может немедленно запретить наличные способы оплаты и попросить продакта перейти только на карты. Позже они могут добавить другой способ оплаты - "штампики", мини-версию программы лояльности кофейни.
  • Разработчики могут упомянуть, что «логика добавки сиропа» немного кривая, поэтому может случиться так, что клиент иногда оказывается со сливками в своей чашке. Поэтому продакт должен решить, ждать ли, пока они это исправят, или удалить это на время из API-контракта.

Другими словами, завязывается хорошая дискуссия, проясняются детали и все стейкхолдеры уходят довольные, что они поняли, что реально будет в решении. Это четкость и есть главная задача продакта, который хочет, чтобы его идея в итоге заработала. Когда все довольны, мяч переходит на сторону технической команды и они начинают кодить - туда продакт уже не лезет.
Пример #2: API прогноза погоды
Представим, что вы — продакт приложения для бегунов и хотите интегрировать прогноз погоды в приложение (не всем нравится бегать под дождем). Вы немного погуглили и нашли этот документ (платного) API погоды:
Input:
  • Location: "Москва"
  • Date/Time: "2028-06-08 15:00:00"

Output:
  • Temperature: "25°C"
  • Weather Condition: "солнечно", "дождь", "облачно" и т.д.
  • Precipitation: "20% вероятность дождя"

Potential errors
  • Неизвестная локация
  • Дата/время в прошлом
Что мы здесь сразу видим? Вы можете передать город (он у вас есть!), дату/время (они тоже есть) и получить температуру в градусах Цельсия, а также погодные условия. А еще:
  • У пользователей будут проблемы в пригородах подальше от городов (поскольку API не поддерживает простые координаты, а только города).
  • Температура указана только в градусах Цельсия (пострадают клиенты из США и прочих стран, где используют Фаренгейты). Поэтому надо будет добавить свой простой "переводчик" между температурами.
  • Ничего не говорится о ветре (бегунам может быть некомфортно, если ветер будет сильнее определенного порога).
Этого достаточно, чтобы либо поставить команде задачу по интеграции с этим API, либо продолжить поиск и найти что-то еще. Обратите внимание, что мы, как продакты, сделали этот анализ всего за несколько минут без всякой помощи технарей.
Пример #3: вызываем MemeAPI самостоятельно
Хватит теории, давайте практиковаться. Как я уже говорил, в мире много API, и вы можете получить от них что угодно: от прогноза погоды до курса валют или стихотворения, написанного ChatGPT. Но сейчас давайте сгенерируем несколько классных мемов через API. Для этого просто кликните на ссылку и вы увидите картинку:

https://api.memegen.link/images/buzz/PMs/ PMs_calling_APIs_everywhere.jpeg
Это был реальный вызов API (так что поздравьте себя!). Вот, что произошло:

  • Ваш браузер обратился по адресу"https://api.memegen.link/images" (это полный адрес API endpoint "Image")
  • Он передал параметры картинки-подложки ("buzz"), текст для вставки наверх ("Product Manager") и вниз ("Just called an API")
  • Сервис мемасов нашел нужную картинку, наложил на нее наш текст (как мы просили) налепил сверху свой штамп в левый нижний угол (хотя мы и не просили) и вернул картинку нам
  • Наш браузер отрисовал картинку на экране

Поскольку надо было передать все параметры в одной строчке адресной строки, то они просто идут один за другим через "/". Бывают и другие способы передачи параметров в API (вы наверняка видели что-то типа &utm_source=blog), но это уже детали, смысл от этого не меняется. Вот тут можете посмотреть на картинку-шпаргалку этого вызова API.

Пример #4: придумываем свой API
Давайте посмотрим на обратный пример: мы хотим сделать свое API и открыть его миру.

Предположим, что мы хотим добавить в наше беговое приложение новую крутую фичу — маршруты для бегунов. Да, Google может построить маршрут для водителей и пешеходов, но бегунам нужно немного другое. Мы предполагаем, что пользователь может указать параметры тренировки и получить идеальный маршрут для пробежки. Запрашиваем у бэкенд команды следующий API:
Input Parameters:
  • Distance: сколько километров пользователь хочет сегодня пробежать
  • Time: то же самое, только в минутах
  • Preference: парки, поля, урбан, вдоль реки - предпочтения по видам
  • Circular or not: круговой маршрут (или нет)

Output Parameters:
  • Array of coordinates (lat, long): список координат для отрисовки на карте
  • Descriptions: список указаний ("На перекрестке поверни налево на ул. Ленина")
  • Total distance: суммарное расстояние

Potential errors
  • Не получилось построить маршрут
  • Расстояние слишком короткое/длинное
  • Данное предпочтение пользователя не поддерживается
  • Системная ошибка
На что тут нужно обратить внимание:
  • Мы не упоминаем, как это будет достигнуто — с помощью модного ML или простого набора правил. Но мы указываем, что пользователи отправляют и чего мы ожидаем в ответ — это уже хорошее начало для переговоров с клиентами и командой.
  • Мы перешли от расплывчатого «маршрута для бегунов» к более конкретному API контракту ввода/вывода. Техническая команда уже обсуждает, как его построить, где они видят пробелы с точки зрения требований. Например, они могут упомянуть, что они вообще не могут поддерживать параметр предпочтения, потому что данные карты не определяют такие детали, как «берег реки» или «город» и т. д. Поэтому продакты могут сразу же снизить планку своих мечтаний и убрать это требование вместо того, чтобы наобещать это всем клиентам и через 2 месяца обнаружить, что это было невозможно с самого начала!
  • Как только API будет готов, можно звать команду-клиента (например, главного приложения) для интеграции и первых тестов.
  • В случае внутреннего успеха можно подумать о том, чтобы "продавать" API спортивным компаниям по всему миру и брать плату за каждую тысячу вызовов API. Даже создатель MemeAPI, которое мы вызывали выше, предлагает перевести ему денег на кофе, чем мы хуже? А если серьезно, множество известных сейчас API (OpenExchangeRate, Stripe, SendBird, и тд) когда-то были просто функционалом внутри продукта. А потом решили начать отдельную жизнь и превратились в отдельные компании.
Главные выводы
Продакт должен помнить следующее:
  • API - это способ отсерсить работу другому сервису или предоставить свои услуги для того, чтобы это сделали другие
  • Описание API состоит из адреса (API endpoint), входных данных (input), выходных данных (output) и возможных ошибок (potential errors).
  • Продакт должен сосредоточиться на основной ценности продукта, а для остального вызывать готовые API. С высокой вероятностью умные разработчики по всему миру уже создали логику, которая вам нужна.

Еще материалы и практика по теме: