1
0
mirror of https://github.com/twirl/The-API-Book.git synced 2025-03-17 20:42:26 +02:00

Section III continued

This commit is contained in:
Sergey Konstantinov 2022-04-23 17:15:02 +03:00
parent 1dff31eb59
commit 72ff626ae8
7 changed files with 71 additions and 25 deletions

View File

@ -0,0 +1,27 @@
### KPI API
Как мы описали выше, существует большое количество различных моделей монетизации API, прямой и косвенной. Важной их особенностью является то, что, во-первых, большинство из них является частично или полностью бесплатными для партнёра, а, во-вторых, соотношение прямой и косвенной выгоды часто меняется в течение жизненного цикла API (что характерно для всех современных IT-стартапов; в этом смысле API не выделяется среди других программных продкетов). Возникает вопрос, каким же образом следует измерять успех API и какие цели ставить продуктовой команде.
Разумеется, наиболее прямым измеримым показателем являются деньги: если ваш API имеет прямую монетизацию либо явно приводит пользователей на монетизируемый сервис, то остальная часть главы будет вам интересна разве что в рамках общего развития. Если же напрямую измерить вклад API в доходы компании не получается, придётся прибегать к иным, синтетическим, показателям.
Очевидный KPI №1 — это количество конечных пользователей и количество интеграций (читай, партнёров, использующих API). В нормальной ситуации он является в определённом смысле барометром состояния бизнеса: если предположить, что на рынке наблюдается здоровая конкуренция между API разных поставщиков, и все находятся в более-менее одинаковом положении, то количество использующих API разработчиков (и как производная — конечных пользователей) и есть главный показатель успеха продукта.
Однако чистые цифры количества пользователей и партнёров могут вводить в заблуждение, особенно в случае бесплатных инсталляций. Есть несколько факторов, искажающих статистику:
* сервисы в линейке API-продуктов, рассчитанные на простую интеграцию (см. соответствующий раздел) существенно искажают статистику количества партнёров в сравнении с конкурентами, если у них таких сервисов нет; зачастую на одну глубокую интеграцию приходятся десятки, если не сотни более простых; таким образом, подсчёт партнёров сдедует как минимум делить по видам интеграции;
* партнёры склонны использовать API неоптимально:
* подключать его на всех страницах / экранах приложения, а не только там, где пользователь реально с ним взаимодействует;
* размещать виджеты глубоко в «подвале» или за спойлером;
* инициализировать широкий набор модулей, но использовать только тривиальную функциональность;
* чем шире распространён ваш API, тем менее значим показатель количества уникальных пользователей, поскольку в какой-то момент проникновение API в сервисы, которыми пользуется целевая аудитория, приблизится к 100%; например, с сервисами Facebook или Google в виде счётчиков и виджетов средний пользователь Интернета встречается чуть ли не ежеминутно, и дневная аудитория этих API уже в принципе вырасти не может.
Вышеперечисленные проблемы приводят нас к простому выводу: считать нужно не только сырые цифры количества уникальных пользотелей и партнёров, но и их вовлечённость, т.е. выделить целевые действия (например, количество поисков через платформу, показ определённых данных, события взаимодействия пользователя с виджетом и т.д.). В идеале эти целевые действия должны коррелировать с монетизацией:
* если API монетизируется за счёт рекламы — считать, сколько раз в день пользователи взаимодействуют с рекламой;
* если API приводит пользователя на сайт материнского сервиса — считать переходы;
* если API используется для сбора обратной связи и UGC — считать оставленные отзывы и исправления.
Наиболее непростая ситуация с KPI наблюдается, если API в первую очередь способ (техно)пиара и (техно)маркетинга. В этом случае наблюдается накопительный эффект: наращивание аудитории не конвертируется в пользу компании моментально. *Сначала* вы набираете большую лояльную аудиторию разработчиков, *потом* репутация вашей компании улучшается, и ещё более потом эта репутация начинает играть вам на руку при найме. *Сначала* логотип вашей компании появляется на сторонних сайтах и приложениях, *потом* top-of-mind знание бренда увеличится. Нет прямого способа отследить, как то или иное действие (например, релиз новой версии или проведение мероприятия) сказывается на целевых показателях. В этом случае приходится оперировать косвенными показателями — посещаемость ресурсов для разработчиков, количество упоминаний в тематических сообществах и т.п.

View File

@ -17,7 +17,11 @@
##### Спецификация / справочник / референс
Любая документация начинается с максимально формального описания доступной функциональности. Да, этот вид документации будет максимально бесполезен с точки зрения удобства использования, но не предоставлять его нельзя — справочник является гигиеническим минимумом. Если у вас нет документа, в котором описаны все методы, параметры и настройки, типы всех переменных и их допустимые значения, зафиксированы все опции и поведения — это не API, а просто какая-то самодеятельность. В идеале референс должен быть представлен в машиночинаемом виде — согласно какому-либо стандарту, например, OpenAPI.
Важно, что специфицкация должна содержать не только формальные описания, но и документировать неявные соглашения, такие как, например, последовательность генерации событий или неочевидные побочные эффекты методов.
Важно, что специфицкация должна содержать не только формальные описания, но и документировать неявные соглашения, такие как, например, последовательность генерации событий или неочевидные побочные эффекты методов. Референс следует рассматривать как наиболее полную из возможных видов документации: выучив референс разрабочик должен будет узнать абсолютно обо всей имеющейся функциональности. Его важнейшее прикладное значение — консультативное: разработчики будут обращаться к нему для прояснения каких-то неочевидных вопросов.
**Важно:** формальная спецификация *не является* документацией сама по себе; документация — это *слова*, которые вы напишете в поле description для каждого поля и метода. Без словесных описаний спецификация годится разве что для проверки, достаточно ли хорошо вы назвали сущности, чтобы разработчик мог догадаться об их смысле самостоятельно.
В последнее время часто описания номенклатуры методов выкладываются также в виде готовых коллекций запросов или фрагментов кода — в частности, для Postman или аналогичных инструментов.
##### Примеры кода
@ -28,8 +32,6 @@
В идеале примеры должны быть провязаны со всеми остальными видами документации. В частности, референс должен содержать примеры, релевантные описанию сущностей.
В последнее время также часто примеры выкладываются в виде готовых коллекций запросов — в частности, для Postman или аналогичных инструментов.
**Песочницы**
Примеры станут намного полезнее для разработчиков, если будут представлены в виде «живого» кода, который можно модифицировать и запустить на исполнение. В случае библиотечных API это может быть просто онлайн-песочница с заранее заготовленными примерами (в качестве такой песочницы можно использовать и существующие онлайн-сервисы типа JSFiddle); в случае других API разработка песочницы может оказаться сложнее:

View File

@ -1,5 +1,7 @@
### Линейка сервисов API
Описанная в предыдущей главе фрагментация пользователей API по профессиональному уровню имеет несколько важнейших следствий, которые необходимо учитывать при разработке:
* практически невозможно в рамках одного продукта создать такой API, который одинаково хорошо подходит и начинающим разработчикам, и профессионалам; первым необходима максимальная простота реализации базовых сценариев использования API, вторым — возможность адаптировать использование API под конкретный стэк технологий и парадигму разработки, и стоящие перед ними задачи, как правило, требуют глубокой кастомизации;
* практически невозможно в рамках одного продукта создать такой API, который одинаково хорошо подходит и начинающим разработчикам, и профессионалам; первым необходима максимальная простота реализации базовых сценариев использования API, вторым — возможность адаптировать использование API под конкретный стек технологий и парадигму разработки, и стоящие перед ними задачи, как правило, требуют глубокой кастомизации;
* абсолютное большинство нагрузки на вашу техническую поддержку будет создавать первая категория: начинающим разработчикам гораздо сложнее найти ответы на свои вопросы или разобраться в проблеме самостоятельно, и они будут задавать их вам;
* при этом вторая категория потребителей будет гораздо более требовательна к качеству как продукта, так и поддержки; при этом удовлетворить их запросы будет крайне нетривиально.
@ -8,7 +10,7 @@
2. Базовый уровень — работы с продуктовыми сущностями посредством формальных интерфейсов. [В случае нашего учебного API этому уровню соответствует HTTP API заказа.]
3. Упростить работу с продуктовыми сущностями можно, предоставив SDK для различных платформ, скрывающие под собой сложности работы с формальными интерфейсами и адаптирующие концепции API под соответствующие парадигмы (что позволяет разработчикам, знакомым только с конкретной платформой, не тратить время и не разбираться в формальных интерфейсах и протоколах.)
4. Ещё более упростить работу можно посредством сервисов, генерирующих код. В таком интерфейсе разработчик выбирает один из представленных шаблонов интеграции, кастомизирует некоторые параметры, и получает на выходе готовый фрагмент кода, который он может вставить в своё приложение (и, возможно, дописать необходимую функциональность с использованием API 1-3 уровней). Подобного рода подход ещё часто называют «программированием мышкой». [В случае нашего кофейного API примером такого сервиса мог бы служить визуальный редактор форм/экранов, в котором пользователь расставляет UI элементы, и в конечном итоге получает полный код приложения.]
5. Ещё более упростить такой подход можно, если результатом работы такого сервиса будет уже не код поверх API, а готовый компонент / виджет / фрейм, подключаемый одной строкой. [Например, если мы дадим возможность разработчику вставлять на свой сайт iframe, в котором можно заказать кофе, кастомизированный под нужды заказчика.]
5. Ещё более упростить такой подход можно, если результатом работы такого сервиса будет уже не код поверх API, а готовый компонент / виджет / фрейм, подключаемый одной строкой. [Например, если мы дадим возможность разработчику вставлять на свой сайт iframe, в котором можно заказать кофе, кастомизированный под нужды заказчика, либо, ещё проще, описать правила формирования URL изображения, который позволит вставить на сайт партнёра баннер с наиболее релевантным предложением.]
В конечном итоге можно прийти к концепции мета-API, когда готовые визуальные компоненты тоже будут иметь какое-то свой высокоуровневый API, который «под капотом» будет обращаться к базовым API.
@ -16,8 +18,8 @@
1. Приложения, использующие физические интерфейсы, полностью вне вашей досягаемости; вы не можете, например, форсировать переход на новые версии технологической платформы или, скажем, добавить в них рекламные размещения.
2. Приложения, оперирующие базовым уровнем API, позволяют вам менять нижележащие уровни абстракции — переходить на новые технологии, манипулировать выдачей и представлением данных.
3. SDK, особенно имеющие визуальные компоненты в составе, дают гораздо более широкий контроль над внешним видом партнерских приложений и их взаимодействием с пользователем, что позволяет развивать UI, добавлять новые виды интерактивных элементов и обогащать функциональность старых. [Например, если SDK нашего кофейного API содержит в себе карту кофеен, ничего не может нам помешать в новой версии SDK сделать объекты на карте кликабельными или, например, выделять оплаченные размещения цветом.]
4. Кодогенерация позволяет вам манипулировать желательным видом приложений. Например, если для вас важным показателем является количество поисков через сторонние приложения, вы можете добавить в генерированный код показ панели поиска на видном месте; пользователи, прибегающие к помощи генератора кода, как правило, не меняют результат.
5. Наконец, готовые компоненты и виджеты находятся полностью под вашим контролем, и вы можете экспериментировать с доступной через них функциональностью так же свободно, как если бы это было ваше собственное приложение.
4. Кодогенерация позволяет вам манипулировать желательным видом приложений. Например, если для вас важным показателем является количество поисков через сторонние приложения, вы можете добавить в генерированный код показ панели поиска на видном месте; пользователи, прибегающие к помощи генератора кода, как правило, не меняют сгенерированный результат.
5. Наконец, готовые компоненты и виджеты находятся полностью под вашим контролем, и вы можете экспериментировать с доступной через них функциональностью так же свободно, как если бы это было ваше собственное приложение. (Здесь следует, правда, отметить, что не всегда от этого контроля есть толк: например, если вы позволяете вставлять изображение по прямому URL, ваш контроль над этой интеграцией практически отсутствует; при прочих равных следует выбирать тот вид интеграции, который позволяет получить больший контроль над соответствущей функциональностью в приложении партнёра.)
**NB**. При разработке семейства API замечания, описанные в главе [«О ватерлинии айсберга»](#chapter-14) особенно важны. Вы можете свободно манипулировать контентом и поведением виджета, если и только если у разработчика нет способа «сбежать из песочницы», т.е. напрямую получить низкоуровневый доступ к объектам внутри виджета.

View File

@ -24,7 +24,8 @@
Этот случай примыкает к предыдущему в том смысле, что потребителем API является разработчик, а не конечный пользователь — с той разницей, что продуктом является не сам API, а сервис, доступ к которому он предоставляет. Чистый пример — это API различных облачных платформ, например, Amazon AWS или Uber Freight API. Да, какая-то работа с платформой возможна и через UI, но без API такие сервисы практически бесполезны. [В нашем кофейном примере — если мы являемся оператором сети кофе-машин, и предоставляем к ним доступ через API.]
Отдельной монетизации в таких случаях, за исключением совсем экзотических, API не имеет, поскольку оплачивается здесь использование самого сервиса. Часто, однако, тарифы исчисляются именно по сущностям API, т.е. тарифицируется количество вызовов методов.
Как правило, тарифицируется в этом случае использование самого сервиса, а не API как такового. Часто, однако, тарифы исчисляются именно по сущностям API, т.е. тарифицируется количество вызовов методов.
##### API = партнёрская программа
@ -48,12 +49,17 @@
Если никакой — ни прямой, ни косвенной — монетизации API не имеет, он всё ещё может приносить доход, развивая знание о компании через брендирование — отображение логотипов и других узнаваемых элементов при работе пользователя с API, нативное (если визуальные интерфейсы отрисовываются непосредственно самим API) или договорное — потребители API обязаны по контракту размещать определённые элементы брендирования там, где используется фунциональность API или предоставленные через него данные. Целью компании-разработчика API в этом случае является или привлечение аудитории на свои основные сервисы, либо продвижение своего бренда в целом. [В случае нашего кофейного API — представим, что мы предоставляем некоторый совершенно иной полезный сервис, допустим, продаём автомобильные шины, а через предоставление API кофе-машин пытается увеличить узнаваемость и заработать себе репутацию технологической компании.]
В этом случае возможны вариации относительно целевой аудитории саморекламы:
* вы можете работать на узнаваемость бренда среди конечных пользователей (размещением своих логотипов и ссылок на сайтах и в приложениях партнёров, использующих API), и даже строить сам бренд таким образом [например, если наш кофейный API будет предоставлять рейтинги кофеен, и мы будем работать на то, чтобы потребитель сам требовал от кофеен указывать рейтинг по версии нашего сервиса];
* вы можете работать на распространение знания о себе среди бизнес-аудитории [например, чтобы партнёры, размещающие у себя виджет заказа кофе, заодно и изучили каталог ваших шин];
* наконец, вы можете распространять API только и исключительно ради того, чтобы заработать себе репутацию среди разработчиков — ради информирования о других ваших продуктов или ради улучшения вашего имиджа как работодателя для ИТ-специалистов.
Дополнительно в этом разделе можно говорить о формировании комьюнити, т.е. сообщества пользователей или разработчиков, лояльных к продукту. Выгоды от существования таких комьюнити бывают довольно существенны: это и снижение расходов на техническую поддержку, и удобный канал информирования о новых сервисах и релизах, и возможность получить бета-тестеров новых продуктов.
##### Сбор обратной связи и UGC
Если через API предоставляется доступ к большим данным, то оправданной может быть стратегия выпуска публичного API для того, чтобы конечные пользователи вносили исправления в данные или иным образом вовлекались в их разметку. Например, провайдеры картографических API часто разрешают сообщить об ошибке или исправить неточность прямо в стороннем приложении. [А в случае нашего кофейного API мы могли бы собирать обратную связь, как пассивно — стоить рейтинги заведений, например, — так и активно — контактировать с владельцами заведений чтобы помочь им исправить недостатки; находить через UGC ещё не подключенные к API кофейни и проактивно работать с ними.]
##### Найм и формирование комьюнити
##### Терраформирование
Наконец, наиболее альтруистический подход к разработке API — предоставление его либо полностью бесплатно либо в формате открытого кода и открытых данных просто с целью изменения ландшафта: если сегодня за API никто не готов платить, то можно вложиться в популяризацию и продвижение функциональности, рассчитывая найти коммерческие ниши (в любом из перечисленных форматов) в будущем или повысить значимость и полезность API в глазах конечных пользователей (а значит и готовность потребителей платить за использование API). [В случае нашего кофейного примера — если компания-производитель умных кофе-машин предоставляет API полностью бесплатно в расчёте на то, что со временем наличие у кофе-машин API станет нормой, и появится возможность разработать новые монетизируемые сервисы за счёт этого.]

View File

@ -1,8 +1,8 @@
1. Зачем предоставлять API
* Зачем предоставлять API
* возможности интеграции с основным сервисом
* непрофильные сервисы
* концепция API-first
2. Выгоды наличия API и виды монетизации
* Выгоды наличия API и виды монетизации
* API к монетизируемым сервисам (+ Affiliate API)
* on-premise
* freemium-модели
@ -15,29 +15,32 @@
* сбор данных / UGC
* контакт с брендом
* терраформирование
3. Прямая и обратная API-пирамида Маслоу
4. Виды API
* KPI
* Прямая и обратная API-пирамида Маслоу
* Виды API
* API
* SDK
* виджеты
* embedded (включая картинки)
5. Бизнес-аудитория, её интересы и места обитания
* идентификация пользователей и фрод
* B2B
* Бизнес-аудитория, её интересы и места обитания
* SLA
* безопасность
* идентификация пользователей, ведение статистики, защита публичных ключей
* контакты и оповещения
6. Разработчики, их интересы и места обитания
* Разработчики, их интересы и места обитания
* новички vs продвинутые
* OpenSource
7. Документация
* Документация
* референс
* tutorial
* how-to
* примеры
* песочница
8. Поддержка пользователей
* Поддержка пользователей
* форумы
* поддержка разработчиков
* работа с комьюнити
* обратная связь
9. Продуктовое управление разработкой API
* Продуктовое управление разработкой API

View File

@ -2,12 +2,18 @@
* разработчики — высокообразованные люди с практически-прикладным рациональным мышлением; как правило, выбор продукта ими осуществляется предельно рационально (это не исключает определённой вкусовщины в части выбора, скажем, языков программирования или вендоров программного обеспечения; однако *повлиять* на эти вкусы практически невозможно);
* в частности, разработчики скептически относятся к громким рекламны заявлениям и готовы разбираться в качестве продукта;
* в частности, разработчики скептически относятся к громким рекламным заявлениям и готовы разбираться в том, насколько эти заявления соответствуют истине;
* к разработчикам крайне сложно обращаться через стандартные маркетинговые каналы; помимо того, что они получают информацию в основном из ускоспециализированных сообществ, программисты также смотрят в первую очередь на мнения, подтверждённые конкретными цифрами и примерами (желательно — примерами кода);
* мнения «инфлюенсеров» в такой среде значат очень мало, поскольку ничьё мнение не принимается на веру;
* идеи Open Source и бесплатного ПО распространены среди разработчиков достаточно широко; попытки в том или ином виде зарабатывать на том, что код вашего проекта остаётся закрытым (например, путём лицензирования интеллектаульной собственности на интерфейсы), будут встречать сопротивление.
* идеи Open Source и бесплатного ПО распространены среди разработчиков достаточно широко; попытки в том или ином виде зарабатывать на том, что код вашего проекта остаётся закрытым (например, путём лицензирования интеллектуальной собственности на интерфейсы), будут встречать сопротивление.
Однако здесь необходимо сделать важную оговорку: в связи с огромной востребованностью информационных технологий в мире значительное количество ваших потребителей не будут профессиональными разработчиками. Огромное количество людей находятся в той или иной фазе освоения профессии: кто-то занимается разработкой в дополнение к основной деятельности, кто-то переучивается, кто-то осваивает азы компьютерных наук самостоятельно. Многие из этих непрофессиональных разработчиков при этом имеют прямое влияние на решение о выборе API — например, владельцы небольших бизнесов, которые по совместительству ещё и занимаются программной реализацией несложных задач.
Однако здесь необходимо сделать важную оговорку: в связи с огромной востребованностью информационных технологий в мире значительное количество ваших потребителей не будут профессиональными разработчиками. Огромное количество людей находятся в той или иной фазе освоения профессии: кто-то занимается разработкой в дополнение к основной деятельности, кто-то переучивается, кто-то осваивает азы компьютерных наук самостоятельно. Многие из этих непрофессиональных разработчиков при этом имеют прямое влияние на решение о выборе API — например, владельцы небольших бизнесов, которые по совместительству ещё и занимаются программной реализацией несложных задач.
Более правильно было бы сказать, что вы работаете на две основные аудитории:
* профессиональных программистов, имеющих широкий опыт интеграции различного рода систем;
* начинающих и полупрофессиональных разработчиков, для которых каждая такого рода интеграция является новой и неизведанной территорией.
Существует мнение, что угодить одновременно обеим аудиториям невозможно: первые ищут возможности глубокой кастомизации (поскольку работают в крупных ИТ-компаниях со сложившимся подходом к разработке), вторым необходим максимально заниженный порог входа. Мы с этим мнением склонны не согласиться по причинам, описанным в следующей главе.

View File

@ -2,7 +2,7 @@
Когда мы говорим об API как о продукте, необходимо чётко зафиксировать два важных тезиса.
1. API — это *такой же продукт*, как и другое ПО. Вы «продаёте» его точно так же, и к нему полностью применимы принципы маркетинга. Весьма сомнительно, что вы сможете качественно продвигать API, не изучив потребности аудитории, спрос и предложение, рынок, конкурентов, потребителей — короче говоря, не проведя всестороннее маркетинговое исследование.
1. API — это *полноценный продукт*, как и другое ПО. Вы «продаёте» его точно так же, и к нему полностью применимы принципы маркетинга. Весьма сомнительно, что вы сможете качественно продвигать API, не изучив потребности аудитории, спрос и предложение, рынок, конкурентов, потребителей — короче говоря, не проведя всестороннее маркетинговое исследование.
2. API — это *очень специфический продукт*. Вы продаёте возможность некоторые действия выполнять автомизированно посредством написания кода, и этот факт накладывает большие ограничения на управление продуктом.
@ -20,8 +20,8 @@
* бизнес, в свою очередь, ставит задачи разработчикам не из чувства стиля и не из соображений красоты кода — заказчика интересует реализация конкретной функциональности, необходимой для решения задач пользователя;
* наконец, пользователю совершенно не интересны проблемы и разработчиков, и бизнеса: он выбирает тот продукт, который ему нужен.
Получается, что пирамида, таким образом, должна строиться снизу вверх: это конечного пользователя нам нужно убедить, что он хочет не какую попало кружку кофе, а именно приготовленную через наш API (и отдельный вопрос, как же мы будем доносить информацию о том, что за API работает под капотом, и почему пользователь должен своими деньгами проголосовать именно за наш API!); тогда бизнес поставит разработчику задачу интегрировать наш API, ну а разработчик уже никуда не денется и напишет код (что, кстати, означает, что вкладываться в читабельность и консистентность API не так уж и обязательно).
Получается, что на вершине пирамиды, таким образом, находится конечный пользователь: это его нам нужно убедить, что он хочет не какую попало кружку кофе, а именно приготовленную через наш API (и отдельный вопрос, как же мы будем доносить информацию о том, что за API работает под капотом, и почему пользователь должен своими деньгами проголосовать именно за наш API!); тогда бизнес поставит разработчику задачу интегрировать наш API, ну а разработчик уже никуда не денется и напишет код (что, кстати, означает, что вкладываться в читабельность и консистентность API не так уж и обязательно).
Истина, разумеется, лежит где-то посередине. В каких-то предметных областях и на каких-то рынках все решения принимаются разработчиками (например, какой фреймворк выбрать); в других областях и рынках конечно слово остаётся за бизнес-заказчиком и конечным пользователем. К тому же, многое зависит от конкурентной ситуации; новому игроку войти на рынок, например, мобильных операционных систем очень дорого и малоперспективно.
Здесь и далее мы будем описывать некоторый «усреднённый» случай, в котором все три яруса пирамиды важны: и пользователи (которые выбирают качественный продукт), и бизнес (которому важны гарантии качества и стоимость разработки), и разработчики (которых интересует удобство работы с API и его функциональность).
Здесь и далее мы будем описывать некоторый «усреднённый» случай, в котором все три яруса пирамиды важны: и пользователи (которые выбирают качественный продукт), и бизнес (которому важны гарантии качества и стоимость разработки), и разработчики (которых интересует удобство работы с API и его функциональность).