assorted drafts

.prettierignore

@@ -0,0 +1 @@
+*.md

src/ru/drafts/04-Раздел III. API как продукт/Идентификация пользователей.md

@@ -0,0 +1,38 @@
+### Идентификация пользователей
+
+В контексте работы с API мы говорим о двух видах пользователей системы:
+
+  * пользователи-программисты, т.е. непосредственно ваши клиенты, разрабатывающие код поверх вашего API;
+  * конечные пользователи, которые будут работать с приложениями, написанными программистами на вашем API.
+
+И тех, и других в большинстве случаев необходимо уметь идентифицировать, т.е. иметь ответы на следующие вопросы:
+
+  * сколько пользователей взаимодействуют с системой (одновременно, в течение дня, месяца, года)
+  * какое количество действий совершает каждый пользователь.
+
+Обладать этой информацией критически важно по двум основным причинам:
+
+  * чтобы понимать пределы прочности системы и уметь планировать её развитие;
+  * чтобы понимать количество ресурсов (в пределе — денег), расходуемых на каждого пользователя.
+
+В случае коммерческих API точность и своевременность сбора этой информации важна вдвойне, поскольку от неё напрямую зависит биллинг; поэтому вопрос *как* мы идентифицируем пользователей — отнюдь не праздный.
+
+#### Идентификация приложений и их владельцев
+
+Начнём с первой категории, то есть пользователей-клиентов API. Сделаем здесь важное уточнение: нам необходимо идентифицровать две различные сущности — приложения и их владельцев.
+
+Приложение — это, грубо говоря, какой-то логически отдельный кейс использования API, чаще всего — в прямом смысле слова приложение (мобильное или десктопное) или веб-сайт, т.е. некоторая техническая сущность, в то время как владелец — это тот, с кем вы заключаете договор использования API, т.е. юридическая сущность. Как правило, лимиты и тарифы устанавливаются на приложения, а идентифицировать вам при этом надо их владельцев.
+
+В современном мире фактический стандарт идентификации (и того, и другого) — это использование API-ключей: разработчик API должен явно получить ключ, оставив свои контактные данные. Ключ, таким образом, идентифицирует приложение, а контактные данные — владельца.
+
+Несмотря на широкое распространение этой практики мы не можем не отметить, что в большинстве случаев она бесполезна, а иногда и вредна. Её несомненным преимуществом является обязанность каждого клиента предоставить актуальные контактные данные, что (теоретически) позволяет связываться с владельцем приложения (что в реальном мире не совсем так — в значительном проценте случаев владелец не читает почту, оставленную в качестве контактной; в случае корпоративных клиентов это вовсе может быть ничейный почтовый ящик или личная почта давно уволившегося сотрудника).
+
+Проблема же API-ключей заключается в том, что они *не позволяют* надёжно идентифицировать ни приложение, ни владельца.
+
+Если API предоставляется с какими-то бесплатными лимитами, то велик соблазн завести множество ключей, оформленных на разных владельцев, чтобы оставаться в рамках бесплатных лимитов. Вы можете повышать стоимость заведения таких мультиаккаунтов, например, требуя привязки номера телефона или кредитной карты, однако и то, и другое — в настоящий момент широко распространённая услуга, и, скорее всего, оплатить виртуальные номера или виртуальные карты (не говоря уже о нелегальных способах приобрести краденые) всегда будет дешевле, чем честно оплачивать использование API. Таким образом, идентификация пользователя по ключам (если только ваш API не является чистым B2B и для его использования нужно подписать физический договор) никак не освобождает от необходимости перепроверять, действительно ли пользователь соблюдает правила и не заводит множество ключей для одного приложения.
+
+Другая опасность заключается в том, что ключ могут банально украсть у добросовестного партнёра. В случае клиентских и веб-приложений это довольно тривиально; в случае серверных приложений проблема стоит гораздо менее остро, но популярный API рано или позно столкнётся с тем, что украденные ключи будут выложены в свободный доступ (или владелец ключа просто будет делиться им со знакомыми по доброте душевной).
+
+Так или иначе, встаёт вопрос независимой валидации: каким образом можно проконтролировать, действительно ли ключ используется в соответствии с пользовательским соглашением.
+
+#### Идентификация конечных пользователей

src/ru/drafts/04-Раздел III. API как продукт/Модели монетизации.md

@@ -0,0 +1,75 @@
+### Модели монетизации API
+
+Как мы неоднократно упоминали в предыдущих разделах, предоставление некоторой функциональности посредством программируемых интерфесов — достаточно дорогое удовольствие. Для создания и поддержания API требуется соответствующий отдел разработки, и публикация API представляет собой принятие определённых обязательств по поддержке, от которых нельзя так просто отказаться. Возникает логичный вопрос, зачем и почему вообще предоставлять функциональность именно в виде API, т.е. продукта для программистов, вместо того, чтобы ограничиться продуктом для конечного потребителя. Рассмотрим здесь различные ситуации, когда публикация API может быть выгодна, а также соответствующие модели монетизации, прямой и косвенной.
+
+##### Разработчик = конечный пользователь
+
+Самая простая и понятная ситуация — в том случае, если разработчики и есть конечные пользователи. В первую очередь здесь речь идёт о всевозможных инструментах для программиста: API языков программирования, фреймворков, операционных систем, библиотек компонентов, игровых движков и так далее, — иными словами, интерфейсы общего назначения. В этом случае ответ на вопрос «зачем предоставлять программный интерфейс» самоочевиден.
+
+Видов монетизации такого API существует множество — по сути, речь идёт о моделях монетизации ПО для разработчиков как таковом.
+
+1. Фреймворк / библиотека / платформа могут быть платными сами по себе, т.е. распространяться под платной лицензией; в настоящее время такие модели становятся всё менее популярны в связи с широким распространением открытого программного обеспечения, но, тем не менее, всё ещё широко распространены.
+
+2. API может быть лицензирован под открытой лицензией с определёнными ограничениями, которые могут быть сняты путём покупки расширенной лицензии; это может быть как ограничение функциональности API (например, запрет публикации приложения в соответствующем магазине приложений или невозможность сборки приложения в продакшен-режиме без приобретения лицензии), так и ограничения на использование (например, открытая лицензия может быть «заразной», т.е. требовать распространения написанного поверх платформы кода под той же лицензией, или же использование бесплатного API может быть запрещено для определённых целей).
+
+3. API может быть бесплатен, но компания-разработчик API может оказывать платные услуги по его консультированию и внедрению или просто продавать расширенную техническую поддержку;
+
+4. Разработка API может спонсироваться явно или неявно владельцем платформы (операционной системы), который заинтересован в том, чтобы разработчики имели как можно больше удобных инструментов для работы с платформой;
+
+5. Наконец, компания-разработчик API путём публикации его под открытой лицензией тем самым привлекает к себе внимание и надеется на повышение продаж других своих продуктов для разработчиков.
+
+Примечательно, что подобные API — чуть ли не единственный «чистый» случай, когда при выборе API разработчик оперирует исключительно соображениями о том, насколько хорош дизайн API, понятна ли документация, продуманы сценарии использования и так далее. Известны случаи, когда сторонние компании или даже пользователи-энтузиасты самостоятельно реализовывали альтернативные имплементации популярного API — так произошло, например, с API языков Java (альтернативная реализация от Google) и C# (проект Mono) — или некоторых отдельных удачных решений в дизайне функциональности (как, например, концепция работы с DOM-деревом посредством выборки элементов CSS-селекторами, изначально появившаяся в проекте cssQuery, позднее была реализована в jQuery, и уже на волне популярности последнего адаптирована непосредственно разработчиками спецификации DOM).
+
+##### API = основной и/или единственный способ доступа к сервису
+
+Этот случай примыкает к предыдущему в том смысле, что потребителем API является разработчик, а не конечный пользователь — с той разницей, что продуктом является не сам API, а сервис, доступ к которому он предоставляет. Чистый пример — это API различных облачных платформ, например, Amazon AWS или Uber Freight API. Да, какая-то работа с платформой возможна и через UI, но без API такие сервисы практически бесполезны.
+
+Отдельной монетизации в таких случаях, за исключением совсем экзотических, API не имеет, поскольку оплачивается здесь использование самого сервиса. Часто, однако, тарифы исчисляются именно по сущностям API, т.е. тарифицируется количество вызовов методов.
+
+##### API = партнёрская программа
+
+Многие коммерческие платформы предоставляют доступ к своей платформе для сторонних разработчиков с целью увеличения продаж или привлечения аудитории на основном сервисе. Примером такого API могут служить, например, партнёрские программы Google Books, Skyscanner Travel APIs или Uber API. В этом случае партнёрство является полностью и исключительно коммерческим: потребители API монетизируют свою собственную аудиторию, а компания — провайдер API таким образом надеется получить доступ к расширенной аудитории, не вкладывая дополнительно в рекламу. Монетизация такого API обычно осуществляется путём фиксации определённых целевых показателей, например, количества кликов по рекламе в отношении к количеству показов.
+
+##### API = дополнительный доступ к сервису
+
+Если некоторая компания располагает некоторой уникальной экспертизой, чаще всего — набором данных, который трудно и/или очень дорого получить самостоятельно, вполне логично возникает спрос и предложение на предоставление этой экспертизы через API. Самый классический пример API такого рода — это картографические API; собрать подробные и точные геоданные и поддерживать их в актуальном виде — очень дорого; при этом чуть ли не все сервисы, которые только можно себе придумать, станут существенно лучше и удобнее, если добавить карту.
+
+Этот кейс — пожалуй что самый интересный с точки зрения разработчика API, поскольку существование программного интерфейса в этом случае действительно является мультипликатором возможностей: компания-владелец экспертизы чисто физически не может сама реализовать все на свете сервисы, эту экспертизу использующие. Предоставление API здесь является «win-win» стратегией: функциональность сторонних сервисов улучшается, а компания-провайдер зарабатывает на этом деньги.
+
+Доступ к API в этом случае может быть безусловно платным, хотя чаще встречаются смешанные модели монетизации: API предоставляется бесплатно до достижения какого-то лимита либо при соблюдении определённых условий (например, для некоммерческих проектов). В отдельных случаях API является полностью бесплатным с целью популяризации определённой платформы, через которую он предоставляется (например, Apple Maps).
+
+Отдельно здесь следует отметить B2B-сервисы. Так как провайдеру сервиса выгодно дать клиенту как можно более разнообразные возможности, а клиенту, в свою очередь, часто требуется максимально гибко использовать имеющуюся функциональность, часто предоставление API — оптимальный выход для обеих сторон. Крупным компаниям, располагающим своими отделами разработки, чаще необходимо запрограммировать свои бизнес-процессы через API и интегрировать их со своими внутренними системами.
+
+##### API как площадка для рекламы
+
+В основном речь здесь идёт о разного рода виджетах и поисковиках: чтобы размещать какую-то рекламу, необходимо иметь прямой доступ к конечному пользователю. Наиболее распространённые API такого типа — это собственно API рекламных сетей, однако встречаются и комбинированные подходы, когда вместе с некоторым API, например, поисковым, «в нагрузку» идёт показ рекламы.
+
+##### API как самореклама
+
+Если никакой — ни прямой, ни косвенной — монетизации API не имеет, он всё ещё может приносить доход, развивая знание о компании через брендирование — отображение логотипов и других узнаваемых элементов при работе пользователя с API, нативное (если визуальные интерфейсы отрисовываются непосредственно самим API) или договорное — потребители API обязаны по контракту размещать определённые элементы брендирования там, где используется фунциональность API или предоставленные через него данные. Целью компании-разработчика API в этом случае является или привлечение аудитории на свои основные сервисы, либо продвижение своего бренда в целом.
+
+##### Сбор обратной связи и UGC
+
+Если через API предоставляется доступ к большим данным, то оправданной может быть стратегия выпуска публичного API для того, чтобы конечные пользователи вносили исправления в данные или иным образом вовлекались в их разметку. Например, провайдеры картографических API часто разрешают сообщить об ошибке или исправить неточность прямо в стороннем приложении.
+
+##### Найм и формирование комьюнити
+
+##### Терраформирование
+
+Наконец, наиболее альтруистический подход к разработке API — предоставление его либо полностью бесплатно либо в формате открытого кода и открытых данных просто с целью изменения ландшафта: если сегодня за API никто не готов платить, то можно вложиться в популяризацию и продвижение функциональности, рассчитывая найти коммерческие ниши (в любом из перечисленных форматов) в будущем или повысить значимость и полезность API в глазах конечных пользователей (а значит и готовность потребителей платить за использование API).
+
+##### Серая зона
+
+Отдельный источник дохода для разработчика API — это анализ запросов, которые делают конечные пользователи или, иными словами, сбор и дальнейшая продажа какой-то информации. Следует иметь в виду, что граница между допустимыми способами обработки информации (например, агрегирование поисковых запросов с целью выделения трендов) и недопустимыми здесь весьма неочевидна и имеет тенденцию меняться как во времени, так и в пространстве (в смысле, одни и те же действия могут быть легальны по одну сторону государственной границы и нелегальны по другую), так что принимать решения о монетизации API подобными способами следует с очень большой осторожностью.
+
+### Подход API-first
+
+В последние годы набирает силу тенденция предоставлять некоторую функциональность в виде API (т.е. продукта для разработчиков) там, где теоретически можно было бы предоставить сервис напрямую конечным пользователям. Этот подход известен как «API-first» и отражает нарастающую специализацию IT-сферы в целом: разработка API выделяется в отдельную компетенцию, которую бизнес готов отдавать сторонним компаниям вместо того, чтобы нанимать штат «универсальных солдат», которые могут разработать и приложение для конечного пользователя, и внутренний API для него. Тем не менее, пока этот подход не является универсально общепринятым, следует помнить о факторах принятия решений, когда можно запускать сервис в формате API-first:
+
+1. Целевой рынок должен быть достаточно «прогрет» — на нём уже должны действовать компании, обладающие достаточным ресурсом для разработки сервисов поверх вашего API, и готовых, к тому же, оплачивать его использование (если только вашей целью не является самореклама или улучшение климата);
+
+2. Качество сервиса не должно страдать от того, что он предоставляется через API;
+
+3. Необходимо реально обладать пресловутой экспертизой в разработке API, иначе велик шанс наделать неисправимых ошибок.
+
+Иногда раздача API является своеобразным «прощупыванием почвы» для того, чтобы компания-разработчик могла оценить рынок и решить, стоит ли выводить на него полноценный пользователский сервис (мы такую практику скорее осуждаем, поскольку она неизбежно приведёт к закрытию API в будущем: либо потому, что рынок оказался не столь привлекателен, как казалось априори; либо потому, что API начнёт создавать конкуренцию материнскому сервису).

src/ru/drafts/04-Раздел III. API как продукт/Пирамиды.md

@@ -0,0 +1,14 @@
+### Прямая и обратная API-пирамида Маслоу
+
+Прежде чем начинать говорить о продукте API, необходимо прояснить важный вопрос: почему вообще возникает необходимость какого-то отдельного подхода к продукту API? Чем он отличается от технологических продуктов вообще? Вопрос этот не праздный, поскольку, по опыту автора настоящей книги, именно попытка относиться к API как к самому обычному программному обеспечению или веб-сервису и есть одновременно самая большая проблема развития продукта.
+
+Ключевое свойство API, о котором мы упоминали ещё в [главе 2](#chapter-2), — это то, что вы не продаёте его конечному пользователю; конечный пользователь взаимодействует с каким-то решением, которое поверх вашего API написали разработчики, работающие на какой-то сторонний бизнес (причём иногда в цепочке между вами и конечным пользователем находится ещё и более одного разработчика). Консистентность, читабельность, продуманная архитектура и вообще качество дизайна API — обо всём этом знает только разработчик. Бизнес-заказчик, а тем более конечный пользователь всех этих красот оценить не может.
+
+При этом разработчики как аудитория продукта — весьма своеобразная категория потребителей. С одной стороны, разработчики, как правило, образованные и активные люди. У них гораздо выше требования к качеству продукта и гораздо шире знания предметной области, чем у конечного пользователя. Замаскировать недостатки продукта агрессивным маркетингом не получится: в тот момент, когда разработчик сядет разбираться с вашим API, все его качества, все достоинства и недостатки по сравнению с конкурентами окажутся как на ладони. При этом разработчики чаще всего имеют прямое, если не решающее влияние на руководство бизнеса в вопросе выбора технологий — следовательно, именно они принимают решение, какой API выбрать.
+
+С этой точки зрения целевая аудитория API — это некоторая пирамида, подобная пирамиде Маслоу:
+  * вершиной пирамиды являются разработчики: именно они непосредственно работают с API, и они выбирают, какой из конкурирующих API им подходит;
+  * средний ярус пирамиды — бизнес-заказчики; они строят продукт, опираясь на разработчиков;
+  * наконец, основание пирамиды — пользователи; им важно решение их задач, и их обычно совершенно не интересует, каким образом оно достигается.
+
+Непосредственный вывод из этой модели звучит так: в достоинствах вашего API в первую очередь необходимо убедить разработчиков; они, в свою очередь, примут решение о выборе технологии, ну а бизнес оттранслирует концепцию пользователям. Если руководителями продукта API являются бывшие или действующие разработчики, они зачастую склонны оценивать конкуренцию на рынке API именно в этом аспекте, и направлять основные усилия по продвижению продукта именно на аудиторию программистов.

src/ru/drafts/04-Раздел III. API как продукт/План.md

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

src/ru/drafts/04-Раздел III. API как продукт/Продукт API.md

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

src/ru/drafts/04-Раздел III. API как продукт/Тестовая среда.md

@@ -0,0 +1,21 @@
+### Тестовая среда
+
+Отдельно стоит обсудить предоставление разработчику возможности протестировать полный цикл работы API автоматически. Во многих предметных областях сделать это отнюдь не просто — в частности, и в нашем выдуманном примере с API кофе-машин. В реальной жизни полный happy path заказа, от запроса пользователем информации о доступных предложения до выставления обратной связи по завершению занимает минуты, иногда десятки минут. Чтобы протестировать какие-то крайние случаи (например, запрос пользователем возврата денежных средств из-за проблем с качеством заказа) требует совершения нескольких десятков последовательных шагов. Ситуация осложняется также тем, что сценарии, связанные с деньгами прямо или косвенно (например, в виде отправки SMS) тестировать «в лоб» накладно. Для облегчения работы с такими API необходима полноценная тестовая среда, с помощью которой разработчики будут обкатывать свой код.
+
+#### Полная симуляция
+
+Очевидное решение — это предоставить специальные сборки SDK или тестовые приложения, с помощью которых разработчик сможет выполнить все необходимые действия. Последовательность шагов при этом ничем не отличается от реального цикла работы: разработчик запускает приложение, создаёт заказы и выполняет прочие действия так, как это делает реальный конечный пользователь системы.
+
+Проблему платежей при этом обычно решают предоставлением специальных тестовых SDK же, где не требуется вводить реальных данных кредитных карт и номеров телефонов, и оплачиваемые действия каким-то образом эмулируются.
+
+Достоинством этого подхода является максимальная приближенность к реальному миру. Недостаток всё тот же: для проверки каждого сценария необходимо вручную (или полуавтоматически с помощью фреймворков типа Selenium) выполнить множество разнообразных действий.
+
+#### API среды тестирования
+
+Исправить ситуацию помогает метапрограммирование: если предоставить API к самой тестовой среде, все эти действия по работе с приложением можно автоматизировать и тем самым существенно ускорить и упростить. Вместо того, чтобы открывать приложение и вручную создавать заказ, разработчик вызывает специальные методы API, которые эмулируют действия пользователя. Это могут быть как реально существующие методы (т.е. по сути внутренний API приложения), так и синтетические функции, разработанные специально для тестирования. Для работы с таким API часто целесообразно предоставлять отдельный SDK или библиотеку готовых вызовов типа коллекции для Postman.
+
+Следует отметить, что API среды тестирования существенно сокращает количество ручной работы, но не время, затраченное на прогон одного сценария: в идеале работа с таким API должна происходить в таком же масштабе времени, что и работа реального приложения, иначе велик шанс пропустить какие-то ошибки, связанные с плохо настроенными интервалами ожидания ответа на запрос, а также увеличивается вероятность false negative ошибок при тестировании, связанных с тем, что реальный код всё-таки работает не мгновенно, а требует определённого (и не всегда предсказуемого) времени для исполнения.
+
+#### Предопределённые сценарии
+
+Альтернативой API среды является эмуляция сценариев работы, когда тестовая среда берёт на себя управление недоступными разработчику действиями. В нашем кофейном примере это будет выглядеть так: после размещения заказа система автоматически эмулирует все шаги его приготовления, а потом и получение заказа конечным пользователем — как правило, в ускоренном масштабе времени. Плюсом такого подхода является наглядная демонстрация, каким образом система работает согласно задумке провайдера API, какие события в какой последовательности генерируются. Основным минусом является необходимость предусмотреть в такой песочнице все возможные unhappy path, т.е. возникающие ошибки, причём также необходимо и предоставить возможность разработчику указать, какой именно из сценариев он хочет воспроизвести. Например, если заказ создан с комментарием определённого вида, будет эмулирована ошибка его исполнения, и разработчик сможет отладить правильную реакцию на такого рода ошибку.