API. Сергей Константинов

Книга делится на 6.5 частей и читается за 8.5 часов.

Немного об авторе. Сергей twirl Константинов 12 лет работал в Яндексе. Из них >6 лет руководил командой разработки API Яндекс Карт. Последний год провёл в Лавке. Сейчас staff в Bolt. Насколько я знаю, он написал две книги: про API и про пиво.

Введение (главы 1-8) даёт информацию о соглашениях, принятых в книге. 

В первом разделе (главы 9-14) рассматриваются основные принципы проектирования API. От того, как правильно разделять абстракции и какие задачи API должно решать, до обширного списка базовых рекомендаций, которые не стоит забывать при создании API. 

Во втором паттерны разработки API (главы 15-25). 

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

• API-first разработка
• очереди заданий в рамках создания асинхронного API
• пагинация (кстати, надо будет традиционно постик обновить)
• поллинг
• массовые изменения
• частичные изменения
• деградация

Речь идёт как о самих паттернах, так и о том, как ими пользоваться (не)стоит. Приправлено это всё смачным количеством примеров. 

В третьем разделе идёт речь про обратную совместимость (главы 26-32). 
Обсуждаются само понятие обратной совместимости, минимальные и достаточные принципы его проектирования. Автор с разных сторон рассматривает проблему нарушения обратной совместимости, когда это делать стоит, а когда стоит смириться, даже если вы хотите исправить ошибку/сделать что-то лучше. Несмотря на всё это, в конце он прагматично замечает, что как бы вы ни старались, всё равно неконсистентности и проблемы в вашем API будут копиться, а вы, как ответственный разработчик, можете лишь замедлить этот процесс. 

В четвёртом разделе рассматривается HTTP API и REST (главы 33-40). 
Разбирается вопрос того, что такое это HTTP API, почему REST это вообще непонятно что, рассматриваются разные форматы данных вроде JSON, Protobuf'ов и других. Дальше вы можете найти подробный (но не слишком) разбор протокола HTTP, рассмотрение различных "правил" при проектировании вашего API и почему следовать им не стоит. 

Например, автор справедливо замечает, что для стандартного CRUD не стоит пользоваться однозначным соответствием HTTP методов и использовать POST + GET + PUT + DELETE, т.к. это может привести к нерасширяемому API. Мы вот у себя в 95% случаев используем POST. В ещё 5% GET. 

В конце раздела рассматривается обработка ошибок и общие рекомендации. 

Про REST хочется повторить отдельно. Впервые термин появился в диссертации Роя Филдинга в 2000м году. В 2008м автор выпустил разъяснение, что же это такое. Суммарно получается, что настоящий REST, это когда клиент не знает ничего про сервер и умеет получать все доступные операции с этого самого сервера, а так же уметь корректно пользоваться этими только что полученными операциями. Ну угарамба. 

В пятом разделе (главы 41-49) обсуждаются клиентские обёртки над API, такие как SDK и UI-библиотеки. Грубо говоря, толстый клиент. 
Тут рассматриваются проблемы и их решения при реализации SDK, в частности, цели, которые ответственный SDK разработчик должен преследовать; проблемы встраивания UI-компонентов, их декомпозицию для максимально удобного использования клиентами, чтобы при этом разработчики не умирали с десятках слоёв абстракций; MV*-подходы разработки и BDUI. 
В целом тема мне не очень близка, однако какие-то базовые концепции я увидел, проблемы осознал. 

В последнем шестом разделе (главы 50-62) обсуждается вопрос разработки API как продукта. 
Сначала приводятся аргументы в пользу того, что API по ряду признаков такой же продукт, как и любой другой, при этом имеющий свою специфику, которую необходимо учитывать для успешного успеха. Далее рассматриваются различные способы ваше API монетизировать в зависимости от того, какого рода услуги вы предоставляете и кто является вашим конечным пользователем. После обсуждается процесс формирования продуктового видения и связанные проблемы, а также рассказывается почему полезно заниматься догфудингом внутри компании, даже если догфудите вы API. Продолжаем обсуждением правильной стратегии выстраивания отношений с разработкой (читай, потенциальными клиентами), бизнесом (клиенты, которые не разработка), а также метрик оценки вашего API продукта. В конце обсуждаются окольные темы: способы идентификации пользователей, в том числе борьба с фродом и несанкционированном доступе; организация саппорта; документация; организация тестовой среды; управление ожиданиями партнёров с точки зрения развития API. 

На этом книга заканчивается. 

Я люблю писать фундаментальные посты на определённые темы. Именно поэтому у меня таких фундаметальных постов не написано несколько десятков. Просто сложно садиться за большой проект. Автор же не побоялся и всё сделал. Книга -- солидный талмуд вокруг довольно узкой темы. В ней освещается реально всё вокруг. В ней много примеров. Написана местами довольно формально, хотя в среднем читается просто и даже хочется хехнуть между делом. Мне очень понравилось, пусть местами и приходилось останавливаться и перечитывать по 2 раза тот или иной кусочек. Или повглядываться в код.

9 GET запросов из 10.