From 862e2bac48ba50edbdbf28f0ba54981d552c38a4 Mon Sep 17 00:00:00 2001 From: Sergey Konstantinov Date: Wed, 15 Jun 2022 01:26:35 +0300 Subject: [PATCH] The 'API KPIs' chapter translated --- .../04-Section III. The API Product/04.md | 2 +- .../04-Section III. The API Product/07.md | 51 +++++++++++++++++++ .../04-Раздел III. API как продукт/04.md | 2 +- .../{06. Линейка сервисов API.md => 06.md} | 10 ++-- .../{07. KPI API.md => 07.md} | 6 +-- 5 files changed, 61 insertions(+), 10 deletions(-) create mode 100644 src/en/drafts/04-Section III. The API Product/07.md rename src/ru/drafts/04-Раздел III. API как продукт/{06. Линейка сервисов API.md => 06.md} (95%) rename src/ru/drafts/04-Раздел III. API как продукт/{07. KPI API.md => 07.md} (97%) diff --git a/src/en/drafts/04-Section III. The API Product/04.md b/src/en/drafts/04-Section III. The API Product/04.md index 445fd29..6359ba8 100644 --- a/src/en/drafts/04-Section III. The API Product/04.md +++ b/src/en/drafts/04-Section III. The API Product/04.md @@ -18,7 +18,7 @@ Let's start with developers. The specifics of software engineers as an auditory Because of the above-mentioned specifics (first of all, the relative insignificance of influencers and the critical attitude towards promotions), you will have to communicate to developers via very specific media: * collective blogs (like the ‘r/programming’ subreddit or dev.to) - * QA sites (Quora, StackOverflow); + * Q&A sites (StackOverflow, Experts Exchange); * educational services (CodeAcademy, Udemy); * technical conferences and webinars. diff --git a/src/en/drafts/04-Section III. The API Product/07.md b/src/en/drafts/04-Section III. The API Product/07.md new file mode 100644 index 0000000..cb99215 --- /dev/null +++ b/src/en/drafts/04-Section III. The API Product/07.md @@ -0,0 +1,51 @@ +### API KPIs + +As we described in the previous chapters, there are many API monetization models, both direct and indirect. Importantly, most of them are fully or conditionally free for partners and the direct to indirect benefits ratio tends to change during the API lifecycle. That naturally leads us to the question of how exactly shall we measure the API success and what goals are to be set for the product team. + +Of course, the most explicit metric is money: if your API is monetized directly or attracts visitors to a monetized service, the rest of the chapter will be of little interest to you, maybe just as a case study. If, however, the contribution of the API to the company's income cannot be simply measured, you have to stick to other, synthetic, indicators. + +Obvious KPI No. 1 is the number of end users and the number of integrations (i.e. partners using the API). Normally, they are in some sense a business health barometer: if there is a normal competitive situation among the API suppliers, and all of them are more or less in the same position, then the figure of how many developers (and consequently, how many end users) are using the API is the main metric of the success of the API product. + +However, sheer numbers might be deceiving, especially if we talk about free-to-use integrations. There are several factors that twist the statistics: + + * the high-level API services that are meant for straightforward integration (see the previous chapter) are significantly distorting the statistics if the competitors don't provide such services; typically, for one full-scale integration there will be tens, maybe hundreds, of those lightweight embedded widgets; thereby, it's crucial to have partners counted for each kind of the integration independently; + + * partners tend to use the API in suboptimal ways: + + * embed it at every site page / application screen instead of only those where end users can really interact with the API; + * put widgets somewhere deep in the page / screen footer, or hide it behind spoilers; + * initialize a broad range of API modules, but use only a limited subset of them; + + * the greater the API auditory is, the less the number of unique visitors means, as at some moment the penetration will be close to 100%; for example, a regular Internet user interacts with Google or Facebook counters, well, every minute, so the daily audience of those API fundamentally cannot be increased further. + +All the abovementioned problems naturally lead us to a very simple conclusion: not only the raw numbers of users and partners are to be gauged, but their engagement as well, e.g. the target actions (e.g. searching, observing some data, interacting with widgets) shall be determined and counted. Ideally, these target actions must correlate with the API monetization model: + + * if the API is monetized through displaying ads, then the user's activity towards those ads (e.g. clicks, interactions) is to be measured; + * if the API attracts customers to the core service, then count the transitions; + * if the API is needed for collecting feedback and gathering UGC, then calculate the number of reviews left and entities edited. + +Often, the functional KPIs are employed: how frequently some API features are used. (Additionally, that helps with prioritizing further API improvements.) In fact, that's still measuring target actions, but those that are made by developers, not end users. It's rather complicated to gather the usage data for software libraries and frameworks, though still doable (however, you must be extremely cautious with that, as any auditory rather nervously reacts to finding that some statistic is gathered automatically). + +The most complicated case is that of API being a tool for (tech)PR and (tech)marketing. In this case, the cumulative effect is observed: increasing the API audience doesn't momentarily bring any profit to the company. *First* you got a loyal developer community, *then* this reputation helps you to hire people. *First* your company's logo flashes on the third-party webpages and applications, *then* the top-of-mind brand knowledge increases. There is no direct method of evaluating how some action (let's say, a new release or an event for developers) affects the target metrics. In this case, you have to operate indirect metrics, such as the audience of the documentation site, the number of mentions in the relevant communication channels, the popularity of your blogs and seminars, etc. + +Let us summarize the paragraph: + * counting direct metrics such as the total number of users and partners is a must and is totally necessary for moving further, but that's not a proper KPI; + * the proper KPI should be formulated based on the number of target actions that are made through the platform; + * the definition of target action depends on the monetization model and might be quite straightforward (like the number of paying partners, or the number of paid ad clicks) or, to the contrary, pretty implicit (like the growth of the company's developer blog auditory). + +#### SLA + +This chapter would be incomplete if we didn't mention the ‘hygienic’ KPI — the service level and the service availability. We won't be describing the concept in detail, as the API SLA isn't any different from any other digital services SLAs. Let us point out that this metric must be tracked, especially if we talk about pay-to-use APIs. However, in many cases, API vendors prefer to offer rather loose SLAs, treating the provided functionality as data access or a content licensing service. + +Still, let us re-iterate once more: any problems with your API are automatically multiplied by the number of partners you have, especially if the API is vital for them, e.g. the API outage makes the main functionality of their services unavailable. (And actually, because of the above-mentioned reasons, the average quality of an integration will imply that partners' services will suffer even if the API is not formally speaking critical for them, but because developers use it excessively and do not bother with proper error handling.) + +It is important to mention that predicting the workload for the API service is rather complicated. Sub-optimal API usage, e.g. initializing the API in those application and website parts where it's not actually needed, might lead to a colossal increase in the number of requests after changing a single line of partner's code. The safety margin for an API service must be much higher than for a regular service for end users — it must survive the situation of the largest partner suddenly starting querying the API on every page and every application screen. (If the partner is already doing that, then the API must survive doubling the load: imagine the partner accidentally starts initializing the API twice on each page / screen.) + +#### Comparing to Competitors + +While measuring KPIs of any service, it's important not only to evaluate your own numbers but also to match them against the state of the market: + * what is your market share, and how it's evolving over time? + * is your service growing faster than the market itself, or the rate is the same, or it's even less? + * what proportion of the growth is caused by the growth of the market, and what is related to your efforts? + +Getting answers to those questions might be quite untrivial in the case of the API services. Indeed, how could you learn how many integrations have your competitor had during the same period of time, and what number of target actions happen on their platform? Sometimes, the providers of popular analytical tools might help you with this, but usually, you have to monitor the potential partners' apps and websites and gather the statistics regarding APIs they're using. The same applies to the market research: unless your niche is significant enough for some analytical company to conduct market research, you will haven to either commission such study or make your own estimations — conversely, through interviewing potential customers. \ No newline at end of file diff --git a/src/ru/drafts/04-Раздел III. API как продукт/04.md b/src/ru/drafts/04-Раздел III. API как продукт/04.md index fefd4e9..3e57c3e 100644 --- a/src/ru/drafts/04-Раздел III. API как продукт/04.md +++ b/src/ru/drafts/04-Раздел III. API как продукт/04.md @@ -18,7 +18,7 @@ В силу этих особенностей аудитории (в первую очередь — малой роли инфлюэнсеров и критического отношения к рекламным заявлениям) доносить информацию до разработчиков приходится через специфические каналы: * коллективные блоги (такие, например, как субреддит ‘r/programming’ или dev.to); - * сайты вопросов и ответов (Quora, StackOverflow); + * сайты вопросов и ответов (StackOverflow, Experts Exchange); * обучающие сервисы (CodeAcademy, Udemy и другие); * технические конференции и вебинары. diff --git a/src/ru/drafts/04-Раздел III. API как продукт/06. Линейка сервисов API.md b/src/ru/drafts/04-Раздел III. API как продукт/06.md similarity index 95% rename from src/ru/drafts/04-Раздел III. API как продукт/06. Линейка сервисов API.md rename to src/ru/drafts/04-Раздел III. API как продукт/06.md index 2b70e5c..4c90269 100644 --- a/src/ru/drafts/04-Раздел III. API как продукт/06. Линейка сервисов API.md +++ b/src/ru/drafts/04-Раздел III. API как продукт/06.md @@ -16,7 +16,7 @@ #### Вертикальное разделение сервисов API -Часто, однако, имеет смысл предоставлять несколько сервисов API, оперирующих одной и той же функциональностью. Дело в том, что описанная в предыдущей главе фрагментация пользователей API по профессиональному уровню имеет несколько важных следствий: +Часто, однако, имеет смысл предоставлять несколько сервисов API, оперирующих одной и той же функциональностью. Дело в том, что описанная в предыдущих главах фрагментация пользователей API по профессиональному уровню имеет несколько важных следствий: * практически невозможно в рамках одного продукта создать такой API, который одинаково хорошо подходит и начинающим разработчикам, и профессионалам; первым необходима максимальная простота реализации базовых сценариев использования API, вторым — возможность адаптировать использование API под конкретный стек технологий и парадигму разработки, и стоящие перед ними задачи, как правило, требуют глубокой кастомизации; * абсолютное большинство нагрузки на вашу техническую поддержку будет создавать первая категория: начинающим разработчикам гораздо сложнее найти ответы на свои вопросы или разобраться в проблеме самостоятельно, и они будут задавать их вам; * при этом вторая категория потребителей будет гораздо более требовательна к качеству как продукта, так и поддержки, и при этом удовлетворить их запросы будет крайне нетривиально. @@ -24,18 +24,18 @@ Самый важный вывод здесь такой: максимально полно покрыть нужды всех категорий пользователей можно только разработав множество продуктов с разным порогом входа и требовательностью к профессиональному уровню программиста. Можно выделить следующие подвиды API, по убыванию требуемого уровня разработчиков. 1. Самый сложный уровень — физического API и семейства абстракций над ними. [В нашем кофейном примере — та часть интерфейсов, которая описывает работу с физическим API кофе машин, см. [главу 9](#chapter-9) и [главу 17](#chapter-17).] 2. Базовый уровень — работы с продуктовыми сущностями через формальные интерфейсы. [В случае нашего учебного API этому уровню соответствует HTTP API заказа.] - 3. Упростить работу с продуктовыми сущностями можно, предоставив SDK для различных платформ, скрывающие под собой сложности работы с формальными интерфейсами и адаптирующие концепции API под соответствующие парадигмы (что позволяет разработчикам, знакомым только с конкретной платформой, не тратить время и не разбираться в формальных интерфейсах и протоколах.) + 3. Упростить работу с продуктовыми сущностями можно, предоставив SDK для различных платформ, скрывающие под собой сложности работы с формальными интерфейсами и адаптирующие концепции API под соответствующие парадигмы (что позволяет разработчикам, знакомым только с конкретной платформой, не тратить время и не разбираться в формальных интерфейсах и протоколах). 4. Ещё более упростить работу можно с помощью сервисов, генерирующих код. В таком интерфейсе разработчик выбирает один из представленных шаблонов интеграции, кастомизирует некоторые параметры, и получает на выходе готовый фрагмент кода, который он может вставить в своё приложение (и, возможно, дописать необходимую функциональность с использованием API 1-3 уровней). Подобного рода подход ещё часто называют «программированием мышкой». [В случае нашего кофейного API примером такого сервиса мог бы служить визуальный редактор форм/экранов, в котором пользователь расставляет UI элементы, и в конечном итоге получает полный код приложения.] - 5. Ещё более упростить такой подход можно, если результатом работы такого сервиса будет уже не код поверх API, а готовый компонент / виджет / фрейм, подключаемый одной строкой. [Например, если мы дадим возможность разработчику вставлять на свой сайт iframe, в котором можно заказать кофе, кастомизированный под нужды заказчика, либо, ещё проще, описать правила формирования URL изображения, который позволит вставить на сайт партнёра баннер с наиболее релевантным предложением.] + 5. Ещё более упростить такой подход можно, если результатом работы такого сервиса будет уже не код поверх API, а готовый компонент / виджет / фрейм, подключаемый одной строкой. [Например, если мы дадим возможность разработчику вставлять на свой сайт iframe, в котором можно заказать кофе, кастомизированный под нужды заказчика, либо, ещё проще, описать правила формирования URL изображения, который позволит показать в приложении партнёра баннер с наиболее релевантным предложением для конечного пользователя.] В конечном итоге можно прийти к концепции мета-API, когда готовые визуальные компоненты тоже будут иметь какое-то свой высокоуровневый API, который «под капотом» будет обращаться к базовым API. -Важнейшим преимуществом наличия линейки продуктов API является не только возможность адаптировать его к уровню разработчика, но и увеличение уровня вашего контроля над кодом, встроенным в приложение партнёра. +Важнейшим преимуществом наличия линейки продуктов API является не только возможность адаптировать его к возможностям конкретного разработчика, но и увеличение уровня вашего контроля над кодом, встроенным в приложение партнёра. 1. Приложения, использующие физические интерфейсы, полностью вне вашей досягаемости; вы не можете, например, форсировать переход на новые версии технологической платформы или, скажем, добавить в них рекламные размещения. 2. Приложения, оперирующие базовым уровнем API, позволяют вам менять нижележащие уровни абстракции — переходить на новые технологии, манипулировать выдачей и представлением данных. 3. SDK, особенно имеющие визуальные компоненты в составе, дают гораздо более широкий контроль над внешним видом партнерских приложений и их взаимодействием с пользователем, что позволяет развивать UI, добавлять новые виды интерактивных элементов и обогащать функциональность старых. [Например, если SDK нашего кофейного API содержит в себе карту кофеен, ничего не может нам помешать в новой версии SDK сделать объекты на карте кликабельными или, например, выделять оплаченные размещения цветом.] 4. Кодогенерация позволяет вам манипулировать желательным видом приложений. Например, если для вас важным показателем является количество поисков через сторонние приложения, вы можете добавить в генерированный код показ панели поиска на видном месте; пользователи, прибегающие к помощи генератора кода, как правило, не меняют сгенерированный результат. - 5. Наконец, готовые компоненты и виджеты находятся полностью под вашим контролем, и вы можете экспериментировать с доступной через них функциональностью так же свободно, как если бы это было ваше собственное приложение. (Здесь следует, правда, отметить, что не всегда от этого контроля есть толк: например, если вы позволяете вставлять изображение по прямому URL, ваш контроль над этой интеграцией практически отсутствует; при прочих равных следует выбирать тот вид интеграции, который позволяет получить больший контроль над соответствущей функциональностью в приложении партнёра.) + 5. Наконец, готовые компоненты и виджеты находятся полностью под вашим контролем, и вы можете экспериментировать с доступной через них функциональностью так же свободно, как если бы это было ваше собственное приложение. (Здесь следует, правда, отметить, что не всегда от этого контроля есть толк: например, если вы позволяете вставлять изображение по прямому URL, ваш контроль над этой интеграцией практически отсутствует; при прочих равных следует выбирать тот вид интеграции, который позволяет получить больший контроль над соответствующей функциональностью в приложении партнёра.) **NB**. При разработке «вертикального» семейства API замечания, описанные в главе [«О ватерлинии айсберга»](#chapter-14) особенно важны. Вы можете свободно манипулировать контентом и поведением виджета, если и только если у разработчика нет способа «сбежать из песочницы», т.е. напрямую получить низкоуровневый доступ к объектам внутри виджета. diff --git a/src/ru/drafts/04-Раздел III. API как продукт/07. KPI API.md b/src/ru/drafts/04-Раздел III. API как продукт/07.md similarity index 97% rename from src/ru/drafts/04-Раздел III. API как продукт/07. KPI API.md rename to src/ru/drafts/04-Раздел III. API как продукт/07.md index 5cac5e1..c1487fc 100644 --- a/src/ru/drafts/04-Раздел III. API как продукт/07. KPI API.md +++ b/src/ru/drafts/04-Раздел III. API как продукт/07.md @@ -26,10 +26,10 @@ Довольно часто встречаются также такие KPI как использование той или иной функциональности API (в том числе для приоритизации планов разработки). По сути это те же целевые действия, но только совершаемые разработчиком, а не пользователем. Для библиотек, особенно клиентских, сбор этой информации бывает затруднён, но не невозможен (хотя крайне желательно подходить к вопросу максимально аккуратно, поскольку любая аудитория сегодня крайне нервно реагирует на автоматический сбор любой статистики). -Наиболее непростая ситуация с KPI наблюдается, если API в первую очередь способ (техно)пиара и (техно)маркетинга. В этом случае наблюдается накопительный эффект: наращивание аудитории не конвертируется в пользу компании моментально. *Сначала* вы набираете большую лояльную аудиторию разработчиков, *потом* репутация вашей компании улучшается, и ещё более потом эта репутация начинает играть вам на руку при найме. *Сначала* логотип вашей компании появляется на сторонних сайтах и приложениях, *потом* top-of-mind знание бренда увеличится. Нет прямого способа отследить, как то или иное действие (например, релиз новой версии или проведение мероприятия) сказывается на целевых показателях. В этом случае приходится оперировать косвенными показателями — посещаемость ресурсов для разработчиков, количество упоминаний в тематических сообществах, посещаемость блогов и семинаров и т.п. +Наиболее непростая ситуация с KPI наблюдается, если API в первую очередь способ (техно)пиара и (техно)маркетинга. В этом случае наблюдается накопительный эффект: наращивание аудитории не конвертируется в пользу компании моментально. *Сначала* вы набираете большую лояльную аудиторию разработчиков, *потом* репутация вашей компании улучшается, и ещё более потом эта репутация начинает играть вам на руку при найме. *Сначала* логотип вашей компании появляется на сторонних сайтах и приложениях, *потом* top-of-mind знание бренда увеличится. Нет прямого способа отследить, как то или иное действие (например, релиз новой версии или проведение мероприятия) сказывается на целевых показателях. В этом случае приходится оперировать косвенными показателями — посещаемость ресурсов для разработчиков, количество упоминаний в тематических сообществах, популярность блогов и семинаров и т.п. Кратко суммируем вышесказанное: - * считать прямые показатели, такие как общее число пользователей и партнёров, — гигиенический минимум, без которого сложно двигаться дальше, но это не KPI; + * считать прямые показатели, такие как общее число пользователей и партнёров, — необходимый минимум, без которого сложно двигаться дальше, но это не KPI; * KPI для продукта API должен выставлять исходя из количества целевых действий, которые производятся через платформу; * определение «целевых действий» зависит от модели монетизации и может быть как прямолинейным «количество платящих клиентов» или «количество кликов по рекламе», так и достаточно опосредованным и эвристическим типа «количество посетителей блога команды разработки». @@ -37,7 +37,7 @@ Невозможно в этом разделе не упомянуть и о «гигиеническом KPI» — уровне предоставляемых услуг и доступности сервиса. Мы не будем здесь давать детального описания, поскольку SLA API ничем не отличается от SLA других видов цифровых сервисов, отметим лишь то, что следить за ним, разумеется, надо, особенно в случае платных API. Впрочем, во многих случаях провайдеры API обычно ограничиваются достаточно свободным SLA, трактуя тарифицируемые услуги как услуги доступа к информации или лицензирование контента. -Тем не менее, позволим себе ещё раз напомнить: любые проблемы вашего API автоматически умножаются на количество партнёров, особенно в тех случаях, когда ваш API критически для них важен, т.е. при неработоспособности API становится недоступной основная функциональность сервиса. (Впрочем, по упомянутым выше причинам качество интеграции бо́льшей части партнёров почти неизбежно будет таково, что ошибки в работе их сервисов будут происходить, даже если ваш API не является формально для них критическим — а потому, что разработчики неправильно написали обработку ошибок.) +Тем не менее, позволим себе ещё раз напомнить: любые проблемы вашего API автоматически умножаются на количество партнёров, особенно в тех случаях, когда ваш API критически для них важен, т.е. при неработоспособности API становится недоступной основная функциональность сервиса. (Впрочем, по упомянутым выше причинам качество интеграции бо́льшей части партнёров почти неизбежно будет таково, что ошибки в работе их сервисов будут происходить, даже если ваш API не является формально для них критическим — а потому, что разработчики подключают API даже там, где оно формально не нужно, и пренебрегают обработкой ошибок.) Важно отметить, что нагрузку на API, вообще говоря, крайне сложно предсказать. Неоптимальное использование API, т.е. его инициализация в тех разделах приложений, где он в реальности не нужен, может привести к колоссальному росту нагрузки вследствие перемещения одной-единственной строки кода партнёра. «Запас прочности» API-сервис должен быть гораздо выше, чем у обычных пользовательских сервисов — как минимум на уровне, достаточном для поддержания его работоспособности в том случае, если крупнейший партнёр начнёт вызывать API при загрузке любой страницы вебсайта / открытии любого экрана приложения. (Если партнёр уже так делает — то API должен переживать как минимум удвоение этой нагрузки на тот случай, если разработчики случайно начнут инициализировать API дважды.)