В книге подробно рассказано, как написать качественный API и интегрировать его в имеющуюся систему. Рассмотрено, как готовить спецификации API, работать с запросами, обслуживать мобильные и серверные API для взаимодействия с базами данных и обмена сообщениями, реализовывать нетривиальную бизнес-логику и подбирать подходящую схему API даже для самых сложных и нечетких задач. Описано, как обеспечивать слабую связность между компонентами, организовывать операции CRUD, осуществлять синхронный и асинхронный обмен данными, в частности, выполнять операции push и poll. Рассказано, как реализовать аутентификацию и идентификацию пользователей. Весь материал базируется на парадигме HTTP REST и позволяет развивать ее в соответствии с современными реалиями и меняющимися требованиями.
Для специалистов по проектированию и поддержке API
API в современных приложениях подобны стыковочным узлам и разъемам. Подход «API-first» — одна из самых горячих современных тем в разработке программного обеспечения.
Многие компании постепенно приходят к пониманию, что уровень API (интерфейсов прикладного программирования) может многократно умножить возможности компании, если спроектировать его правильно. Однако некачественные или неудобные в поддержке API могут превратиться в источник хронических проблем, так что лучше сразу делать их правильно и предусматривать поддержку и расширяемость.
Эта книга написана с целью изложения лучших практик разработки API. Книга состоит из шести разделов, посвящённых:
- проектированию API;
- паттернам дизайна API;
- поддержке обратной совместимости;
- HTTP API и архитектурным принципам REST;
- SDK и библиотекам для пользовательского интерфейса (UI);
- управлению API как продуктом.
С книгой вы научитесь:
- проектировать интерфейсы и писать их спецификации;
- организовывать синхронный и асинхронный обмен данными
- реализовывать модели push и poll
- обеспечивать слабую связность между компонентами
- выполнять операции CRUD
- программировать бизнес-логику API
- гарантировать надёжную идентификацию и аутентификацию пользователей.
Константинов Сергей работает с API уже больше десяти лет. Начинал свою карьеру в подразделении по разработке API Яндекс-Карт и со временем стал руководителем всего сервиса, где отвечал за техническую составляющую Яндекс-Карт и за управление продуктом. Обладает уникальным опытом построения крупномасштабных API мирового уровня для сервисов, которыми ежедневно пользуются десятки миллионов человек. В течение полутора лет проработал в составе группы технической архитектуры W3C.
Книгу “API как искусство: разработка, поддержка, интеграция” можно купить в нашем интенет-магазине.
Введение………………………………………………………………………………………………….. 9
О структуре этой книги……………………………………………………………………………………………………………….. 9
Определение API………………………………………………………………………………………………………………………… 10
Критерии качества API……………………………………………………………………………………………………………… 11
Выбор подхода к разработке API…………………………………………………………………………………………….. 13
Подход API-first………………………………………………………………………………………………………………………….. 13
Обратная совместимость…………………………………………………………………………………………………………… 14
О версионировании……………………………………………………………………………………………………………………. 15
Условные обозначения и терминология………………………………………………………………………………….. 15
Часть I. Проектирование API………………………………………………………. 19
Глава 1. Пирамида контекстов API. Определение области применения…. 21
Почему API?……………………………………………………………………………………………………………………………….. 23
Что и как?……………………………………………………………………………………………………………………………………. 23
Глава 2. Разделение уровней абстракции……………………………………………….. 24
Изоляция уровней абстракции………………………………………………………………………………………………….. 34
Потоки данных…………………………………………………………………………………………………………………………… 36
Глава 3. Разграничение областей ответственности…………………………………. 38
Сценарии использования………………………………………………………………………………………………………….. 39
Хелперы………………………………………………………………………………………………………………………………………. 42
Обработка ошибок…………………………………………………………………………………………………………………….. 43
Декомпозиция интерфейсов. Правило «7±2»…………………………………………………………………………… 44
Глава 4. Описание конечных интерфейсов…………………………………………….. 47
- Важное уточнение номер один: правила не должны применяться бездумно………………….. 47
- Явное лучше неявного…………………………………………………………………………………………………………… 48
- Указывайте использованные стандарты……………………………………………………………………………… 49
- Сущности должны именоваться конкретно…………………………………………………………………………. 50
- Не экономьте буквы……………………………………………………………………………………………………………….. 50
- Тип поля должен быть ясен из его названия………………………………………………………………………… 51
- Подобные сущности должны называться подобно и вести себя подобным образом……… 52
- Избегайте двойных отрицаний……………………………………………………………………………………………… 53
- Избегайте неявного приведения типов…………………………………………………………………………………. 53
- Декларируйте технические ограничения явно………………………………………………………………….. 55
- Любые запросы должны быть лимитированы………………………………………………………………….. 55
- Описывайте политику перезапросов………………………………………………………………………………….. 56
- Подсчитывайте трафик……………………………………………………………………………………………………….. 56
- Отсутствие результата — тоже результат………………………………………………………………………… 57
- Валидируйте ввод………………………………………………………………………………………………………………… 58
- Значения по умолчанию должны быть осмысленны……………………………………………………….. 60
- Ошибки должны быть информативными…………………………………………………………………………… 61
- Всегда показывайте неразрешимые ошибки прежде разрешимых…………………………………. 62
- Начинайте исправление ошибок с более глобальных……………………………………………………… 63
- Проанализируйте потенциальные взаимные блокировки……………………………………………….. 64
- Указывайте время жизни ресурсов и политики кеширования………………………………………….. 65
- Сохраняйте точность дробных чисел………………………………………………………………………………… 66
- Все операции должны быть идемпотентны………………………………………………………………………. 67
- Не изобретайте безопасность…………………………………………………………………………………………….. 69
- Помогайте партнерам не изобретать безопасность…………………………………………………………. 70
- Используйте глобально уникальные идентификаторы……………………………………………………. 71
- Предусмотрите ограничения доступа……………………………………………………………………………….. 72
- Не предоставляйте функциональность массового получения
чувствительных данных………………………………………………………………………………………………………. 72 - Локализация и интернационализация……………………………………………………………………………….. 73
Часть II. Паттерны дизайна API…………………………………………………. 75
Глава 5. О паттернах проектирования в контексте API…………………………. 77
Принципы решения типовых проблем проектирования API………………………………………………….. 78
Глава 6. Аутентификация партнеров и авторизация вызовов API………….. 79
Глава 7. Стратегии синхронизации………………………………………………………… 81
Программные блокировки…………………………………………………………………………………………………………. 82
Оптимистичное управление параллелизмом………………………………………………………………………….. 83
Глава 8. Слабая консистентность…………………………………………………………… 84
Событийная консистентность…………………………………………………………………………………………………… 84
Риски перехода к событийной консистентности…………………………………………………………………….. 86
Глава 9. Асинхронность и управление временем……………………………………. 89
Глава 10. Списки и организация доступа к ним…………………………………….. 93
Иммутабельные списки……………………………………………………………………………………………………………… 97
Пополняемые списки, иммутабельные данные……………………………………………………………………….. 97
Общий сценарий………………………………………………………………………………………………………………………. 101
Глава 11. Двунаправленные потоки данных. Push- и poll-модели…………. 103
Доставка сообщений на клиентское устройство………………………………………………………………….. 104
- Дуплексные соединения………………………………………………………………………………………………. 104
- Раздельный канал обратного вызова и асинхронные потоки событий………………….. 105
- Сторонние сервисы отправки push-уведомлений……………………………………………………… 105
Использование push-технологий в публичном API………………………………………………………………. 106
Доставка сообщений backend-to-backend…………………………………………………………………………….. 107
Типичные проблемы интеграции через webhook………………………………………………………………….. 108
Очереди сообщений…………………………………………………………………………………………………………………. 110
Глава 12. Асинхронная обработка событий.
Атомарность массовых изменений……………………………………………………….. 111
Глава 13. Частичные обновления…………………………………………………………. 119
Варианты решения………………………………………………………………………………………………………………….. 120
Разрешение конфликтов совместного редактирования………………………………………………………… 124
Глава 14. Деградация и предсказуемость……………………………………………… 125
Часть III. Обратная совместимость……………………………………… 127
Глава 15. Постановка проблемы обратной совместимости…………………… 129
Фрагментация клиентских приложений………………………………………………………………………………… 130
Эволюция предметной области……………………………………………………………………………………………… 132
Дрифт платформ………………………………………………………………………………………………………………………. 132
Обратная совместимость на уровне спецификаций……………………………………………………………… 133
Политика обратной совместимости……………………………………………………………………………………….. 134
Глава 16. О ватерлинии айсберга…………………………………………………………. 136
- Предоставляйте минимальный объем функциональности………………………………………………. 136
- Избегайте «серых зон» и недосказанности………………………………………………………………………… 137
- Фиксируйте неявные договоренности………………………………………………………………………………… 137
- Продуктовая логика тоже должна быть обратно совместимой………………………………………. 140
Глава 17. Расширение через абстрагирование………………………………………. 141
Границы применимости………………………………………………………………………………………………………….. 144
Глава 18. Сильная связность и сопутствующие проблемы…………………… 145
Правило контекстов…………………………………………………………………………………………………………………. 147
Глава 19. Слабая связность………………………………………………………………….. 151
Инверсия ответственности………………………………………………………………………………………………………. 156
Делегируй!………………………………………………………………………………………………………………………… 158
Интерфейсы как универсальный паттерн……………………………………………………………………………… 159
Глава 20. «Блокнот душевного покоя»…………………………………………………. 161
- Помните о подводной части айсберга……………………………………………………………………………….. 161
- Тестируйте формальные интерфейсы………………………………………………………………………………… 161
- Изолируйте зависимости…………………………………………………………………………………………………….. 162
- Реализуйте функциональность своего API поверх публичных интерфейсов…………………. 162
- Заведите блокнот…………………………………………………………………………………………………………………. 163
Часть IV. HTTP API и архитектурные принципы REST……….. 165
Глава 21. О концепции HTTP API. Парадигмы разработки
клиент-серверного взаимодействия………………………………………………………. 167
Глава 22. Преимущества и недостатки HTTP (REST) API в сравнении с альтернативными технологиями……………………………………………………………………………………….. 171
- Машиночитаемость метаданных……………………………………………………………………………………….. 173
- Качество решений……………………………………………………………………………………………………………….. 174
- Вопросы производительности……………………………………………………………………………………………. 175
Преимущества и недостатки формата JSON…………………………………………………………………………. 176
Выбор технологии разработки клиент-серверного API……………………………………………………….. 177
Технология gRPC……………………………………………………………………………………………………………… 178
Технология GraphQL……………………………………………………………………………………………………….. 178
Мифология REST……………………………………………………………………………………………………………………… 179
Глава 23. Составляющие HTTP-запросов и их семантика……………………. 182
- URL……………………………………………………………………………………………………………………………………….. 183
- Заголовки……………………………………………………………………………………………………………………………… 185
- HTTP-глаголы………………………………………………………………………………………………………………………. 186
- Статус-коды…………………………………………………………………………………………………………………………. 188
Важное замечание о кешировании………………………………………………………………………………………… 189
Важное замечание о консистентности…………………………………………………………………………………… 189
Глава 24. Организация HTTP API согласно принципам REST……………… 191
Пример построения HTTP API………………………………………………………………………………………………… 192
Авторизация stateless-запросов………………………………………………………………………………………………. 199
Глава 25. Разработка номенклатуры URL-ресурсов. CRUD-операции….. 200
- Где заканчиваются метаданные операции и начинаются «просто» данные
и насколько допустимо дублировать поля и там и там?………………………………………………….. 201 - Каким образом организовывать эндпойнты, связывающие две сущности, междукоторыми нет явных отношений подчинения?………………………………………………………………………………………………………………………….. 202
- Насколько строго должна выдерживаться буквальная интерпретация
конструкции ГЛАГОЛ /ресурс?……………………………………………………………………………………………. 202
CRUD-операции……………………………………………………………………………………………………………………….. 204
- Создание……………………………………………………………………………………………………………………….. 205
- Чтение……………………………………………………………………………………………………………………………. 206
- Редактирование……………………………………………………………………………………………………………. 207
- Удаление……………………………………………………………………………………………………………………….. 207
CRUD-операции в реальной жизни………………………………………………………………………………… 207
Глава 26. Работа с ошибками в HTTP API……………………………………………. 209
Клиентские ошибки…………………………………………………………………………………………………………………. 210
Серверные ошибки…………………………………………………………………………………………………………………… 213
Организация системы ошибок в HTTP API на практике………………………………………………………. 215
Глава 27. Заключительные положения и общие рекомендации……………. 215
Часть V. SDK- и UI-библиотеки………………………………………………….. 219
Глава 28. Терминология. Обзор технологий разработки SDK……………….. 221
Выбор фреймворка для разработки UI-компонентов…………………………………………………………… 222
Глава 29. SDK: проблемы и решения……………………………………………………. 223
Кодогенерация…………………………………………………………………………………………………………………………. 228
Другие инструменты……………………………………………………………………………………………………………….. 229
Глава 30. Проблемы встраивания UI-компонентов………………………………. 229
Проблемы…………………………………………………………………………………………………………………………………. 230
- Объединение в одном объекте разнородной функциональности…………………………….. 231
- Общее владение ресурсами…………………………………………………………………………………………. 231
- Множественная иерархия подчинения сущностей…………………………………………………… 232
Глава 31. Декомпозиция UI-компонентов…………………………………………….. 234
Глава 32. MV*-фреймворки………………………………………………………………….. 247
Паттерн «модель»…………………………………………………………………………………………………………………….. 249
Backend-Driven UI……………………………………………………………………………………………………………………. 251
Глава 33. Разделяемые ресурсы и асинхронные блокировки……………….. 254
Глава 34. Вычисляемые свойства…………………………………………………………. 258
Варианты подходов………………………………………………………………………………………………………………… 259
Вычисленные значения…………………………………………………………………………………………………………… 260
Глава 35. Заключение к части V………………………………………………………….. 260
Часть VI. API как продукт…………………………………………………………… 261
Глава 36. Продукт API. Бизнес-модели API………………………………………….. 263
Основные модели монетизации API……………………………………………………………………………………….. 265
- Разработчик = конечный пользователь……………………………………………………………………… 265
- API = основной и/или единственный способ доступа к сервису……………………………… 266
- API = партнерская программа…………………………………………………………………………………….. 266
- API = дополнительный доступ к сервису…………………………………………………………………… 267
- API = площадка для рекламы……………………………………………………………………………………… 268
- API = самореклама и самопиар…………………………………………………………………………………… 268
- API = инструмент получения обратной связи и UGC………………………………………………… 269
- Терраформирование…………………………………………………………………………………………………….. 269
- «Серая зона»…………………………………………………………………………………………………………………. 270
Подход API-first……………………………………………………………………………………………………………………….. 270
Глава 37. Формирование продуктового вдения………………………………….. 271
Продуктовое вдение API……………………………………………………………………………………………………….. 271
Проверка продуктовых гипотез……………………………………………………………………………………………… 272
Глава 38. Взаимодействие с разработчиками и бизнес-аудиторией………. 273
Open Source………………………………………………………………………………………………………………………………. 275
Фрагментация аудитории……………………………………………………………………………………………………….. 276
Взаимодействие с бизнес-аудиторией…………………………………………………………………………………… 277
Глава 39. Линейка сервисов API………………………………………………………….. 278
Горизонтальное разделение сервисов API……………………………………………………………………………. 278
Вертикальное разделение сервисов API………………………………………………………………………………… 279
Глава 40. Ключевые показатели эффективности API……………………………. 281
SLA……………………………………………………………………………………………………………………………………………. 283
Сравнение с конкурентами……………………………………………………………………………………………………… 284
Глава 41. Идентификация пользователей и борьба с фродом……………….. 285
Идентификация приложений и их владельцев………………………………………………………………………. 285
Идентификация конечных пользователей……………………………………………………………………………… 288
Глава 42. Технические способы борьбы с несанкционированным доступом к API 289
- Идентификация подозрительных пользователей……………………………………………………………… 289
- Запрос дополнительного фактора аутентификации………………………………………………………… 290
- Ограничение доступа………………………………………………………………………………………………………….. 290
Противодействие краже ключей…………………………………………………………………………………………….. 292
Глава 43. Поддержка пользователей API……………………………………………… 293
Документация…………………………………………………………………………………………………………………………… 295
Виды справочных материалов……………………………………………………………………………………………….. 296
- Спецификация/справочник/референс…………………………………………………………………………. 296
- Примеры кода……………………………………………………………………………………………………………….. 297
- Песочницы…………………………………………………………………………………………………………………….. 297
- Руководство (туториал)……………………………………………………………………………………………….. 298
- Часто задаваемые вопросы и база знаний…………………………………………………………………. 299
- Офлайн-документация…………………………………………………………………………………………………. 299
Проблемы дублирования контента………………………………………………………………………………………… 299
Качество документации………………………………………………………………………………………………………….. 300
Тестовая среда…………………………………………………………………………………………………………………………. 300
- API среды тестирования………………………………………………………………………………………………. 301
- Симулятор предопределенных сценариев…………………………………………………………………. 302
Автоматизация тестирования…………………………………………………………………………………………………. 302
Глава 44. Управление ожиданиями………………………………………………………. 303
Версионирование и жизненный цикл приложений……………………………………………………………….. 303
Поддержка платформ………………………………………………………………………………………………………………. 304
Движение вперед……………………………………………………………………………………………………………………… 304
