Проектирование веб-API

Интернет-магазин: www.dmkpress.com

Оптовая продажа: КТК “Галактика”
books@alians-kniga.ru
www.дмк.рф

Проектирование веб-API

Проектирование веб-API

Проектирование
веб-API

API позволяет разработчикам выполнять 
интеграцию с приложением без знания 
подробностей на уровне кода. Независимо от того, используете ли вы установленные стандарты, такие как REST 
и OpenAPI, или более новые подходы, 
такие как GraphQL или gRPC, освоение 
проектирования API – своего рода суперспособность. Благодаря этому пользоваться вашими веб-сервисами станет 
легче, и ваши клиенты, как внутренние, 
так и внешние, это оценят.

«Автор раскрывает тему просто 
и доступно, рассматривая широкий круг вопросов в удобной 
для читателя форме».
Из предисловия Кина Лейна

«Книга дает ответы на насущные сложные вопросы с помощью простой философии, 
ничего при этом не утаивая и 
предлагая фантастическое знакомство с данной темой».
Бриджер Хауэлл, SoFi.com 

«Отличный путеводитель по 
RESTful API».
Шон Смит, Университет 
штата Пенсильвания

«Разнообразные теоретические 
положения сочетаются здесь с 
практическими примерами».
Шейн Корнуэлл, XeroOne Systems

Темы, затрагиваемые в книге:
• характеристики правильно разработанного API;
• ориентированные на пользователя и реальные API;
• принцип Secure by design;
• изменение API, его документирование и проверка. 

Книга предназначена для разработчиков с минимальным 
опытом в создании и использовании API.

Арно Лоре – архитектор программного обеспечения с большим опытом работы в банковской сфере. В течение 10 лет 
использует, проектирует и создает API. Он ведет блог под 
названием API Handyman и создал сайт API Stylebook.

Арно Лоре

9 785970 608616

ISBN 978-5-97060-861-6

Проектирование
веб-API

Арно Лоре

Проектирование веб-API

The Design of Web APIs

ARNAUD LAURET

Foreword by Kin Lane

Проектирование веб-API

Арно Лоре

Предисловие Кина Лейна

Москва, 2020

УДК 004.432
ББК 32.972.1

Л78

Л78
Арно Лоре
Проектирование веб-API / Пер. с англ. Д. А. Беликова. – М.: ДМК Пресс, 
2020.– 440 с.
ISBN 978-5-97060-861-6

Книга, написанная с учетом многолетнего опыта автора в разработке API, научит вас, как собирать требования, как найти баланс между техническими и бизнес-целями и как принимать во внимание запросы потребителя. Рассматриваются основные характеристики API, принципы его изменения, документирования 
и проверки. Эффективные методы разработки проиллюстрированы множеством 
интересных примеров.
Рассматриваются основные характеристики API, принципы его изменения, документирования и проверки. Эффективные методы разработки проиллюстрированы множеством интересных примеров.
Издание предназначено для разработчиков, обладающих минимальным опытом в создании и использовании API-интерфейсов.

УДК 004.432
ББК 32.972.1

Original English language edition published by Manning Publications USA, USA. Copyright © 2018
Russian-language edition copyright © 2020 by DMK Press. All rights reserved.
Все права защищены. Любая часть этой книги не может быть воспроизведена в какой бы то 
ни было форме и какими бы то ни было средствами без письменного разрешения владельцев авторских прав.

ISBN 978-5-97060-861-6 (рус.)
© 2019 by Manning Publications Co.
ISBN 978-1-61729-510-2 (анг.)
© Оформление, издание, ДМК Пресс, 2020

Оглавление

Часть I. Основы проектирования API. . . . . . . . . . . . . .28

1 ■ Что такое проектирование API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
2 ■ Проектирование API для пользователей . . . . . . . . . . . . . . . . . . . . . .45
3 ■ Проектирование программного интерфейса . . . . . . . . . . . . . . . . . .75
4 ■ Описание API с помощью формата описания. . . . . . . . . . . . . . . . .111

Часть II. Проектирование практичного API . . .149

5 ■ Проектирование простого API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
6 ■ Проектирование предсказуемого API  . . . . . . . . . . . . . . . . . . . . . . .183
7 ■ Проектирование лаконичного и хорошо организованного API  213

Часть III. Контекстное проектирование API. . . 233

8 ■ Проектирование безопасного API  . . . . . . . . . . . . . . . . . . . . . . . . . .235
9 ■ Изменение дизайна API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
10 ■ Проектирование эффективного API для сети  . . . . . . . . . . . . . . . .311
11 ■ Проектирование API в контексте . . . . . . . . . . . . . . . . . . . . . . . . . . .345
12 ■ Документирование API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
13 ■ Развитие API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413

Содержание

Предисловие . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
От автора . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Благодарности. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Об этой книге  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Об авторе. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Об иллюстрации на обложке . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Часть I. Основы проектирование API. . . . . . . . . . . . . .28
1 

Что такое проектирование API . . . . . . . . . . . . . . . . . . . . . . . .29
1.1. Что такое API?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
1.1.1. API – это веб-интерфейс для программного обеспечения . . .30
1.1.2.  API превращают программное обеспечение в детали 
конструктора LEGO® . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

1.2. Чем важна разработка API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
1.2.1.  Открытый или закрытый API – это интерфейс  
для других разработчиков  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.2.2 API создается, для того чтобы скрыть реализацию  . . . . . . . 37
1.2.3. Страшные последствия плохо спроектированных API. . . . . .38

1.3. Элементы проектирования API . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
1.3.1  Изучение принципов, выходящих за рамки проектирования 
программного интерфейса  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .42
1.3.2 Изучение всех аспектов проектирования API  . . . . . . . . . . . . . 43

2 

Проектирование API для пользователей  . . . . . . . . . . . . .45
2.1 
Правильная точка зрения для проектирования  
повседневных пользовательских интерфейсов  . . . . . . . . . . . 46
2.1.1  Когда вы фокусируетесь на том, как все работает, это 
приводит к возникновению сложных интерфейсов  .  .  .  .  .  .  .  .  . 46

Содержание

2.1.2  Когда вы фокусируетесь на том, что могут делать 
пользователи, это приводит к появлению простых 
интерфейсов  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

2.2 
Проектирование интерфейсов  
программного обеспечения . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.2.1 API как панель управления программным обеспечением  .  .  .  . 50
2.2.2  Ориентация на точку зрения потребителя  
для создания простых API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

2.3 
Определение целей API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
2.3.1 Отвечая на вопросы «что?» и «как?»  . . . . . . . . . . . . . . . . . . . . 55
2.3.2 Определение входных и выходных данных . . . . . . . . . . . . . . . . . 56
2.3.3 Выявляем недостающие цели . . . . . . . . . . . . . . . . . . . . . . . . . . .58
2.3.4 Идентификация всех пользователей . . . . . . . . . . . . . . . . . . . . . 61
2.3.5 Использование таблицы целей API  . . . . . . . . . . . . . . . . . . . . . . 62

2.4 
Избегаем точки зрения поставщика  
при проектировании API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
2.4.1 Как избежать влияния данных . . . . . . . . . . . . . . . . . . . . . . . . . . 65
2.4.2 Как избежать влияния кода и бизнес-логики . . . . . . . . . . . . . . 67
2.4.3 Как избежать влияния архитектуры программного 
обеспечения . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
2.4.4 Как избежать влияния организации, где работают люди . . .70
2.4.5 Определение точки зрения поставщика  
в таблице целей API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

3 

Проектирование программного интерфейса  . . . . . . . .75
3.1 Знакомство с REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.1.1 Анализ вызова REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.1.2 Базовые принципы HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
3.1.3 Базовые принципы REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

3.2 Перенос целей в REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.2.1 Идентификация ресурсов и их связей с таблицей  
целей API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.2.2  Идентификация действий, их параметров и результатов 
с помощью таблицы целей API . . . . . . . . . . . . . . . . . . . . . . . . . .84
3.2.3 Представление ресурсов с помощью путей  . . . . . . . . . . . . . . . 86
3.2.4 Представление действий с помощью протокола HTTP . . . . .88
3.2.5 REST API и шпаргалка по HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 92

3.3 Проектирование  данных API  . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
3.3.1 Проектирование  концепций  . . . . . . . . . . . . . . . . . . . . . . . . . . .94
3.3.2 Проектирование  ответов от концепций  . . . . . . . . . . . . . . . . 97
3.3.3 Проектирование  параметров из концепций или ответов . .98
3.3.4 Проверка параметров источника данных . . . . . . . . . . . . . . . .99
3.3.5 Проектирование других параметров  . . . . . . . . . . . . . . . . . . . 101

3.4 Достижение баланса при решении проблем  
проектирования. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.4.1 Примеры компромисса. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Содержание
9

3.4.2 Баланс между удобством для пользователя  
и соответствием . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

3.5 Почему REST важен при проектировании любого API . . . .104
3.5.1 Знакомство с архитектурным стилем REST  . . . . . . . . . . . .104
3.5.2 Влияние ограничений REST на проектирование API . . . . . . . 106

4 

Описание API с помощью формата описания . . . . . . .111
4.1 Что такое формат описания API?  . . . . . . . . . . . . . . . . . . . . . . . . 112
4.1.1 Спецификация OpenAPI (OAS)  . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.1.2 Зачем использовать формат описания API? . . . . . . . . . . . . . 115
4.1.3 Когда использовать формат описания API  . . . . . . . . . . . . . .118

4.2 Описание ресурсов и действий API с помощью OAS . . . . . .119
4.2.1 Создание документа OAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
4.2.2 Описание ресурса . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
4.2.3 Описание операций в ресурсе  . . . . . . . . . . . . . . . . . . . . . . . . . . 122

4.3 Описание данных API с помощью OpenAPI  
и JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
4.3.1 Описание параметров запроса. . . . . . . . . . . . . . . . . . . . . . . . . 127
4.3.2 Описание данных с помощью JSON Schema . . . . . . . . . . . . . . .130
4.3.3 Описание ответов . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
4.3.4 Описание параметров тела . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

4.4 Эффективное описание API с помощью OAS . . . . . . . . . . . . .140
4.4.1 Повторное использование компонентов  . . . . . . . . . . . . . . . .140
4.4.2 Описание параметров пути  . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Часть II. Проектирование практичного API  . .149
5 

Разработка простого API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
5.1 Разработка простых представлений . . . . . . . . . . . . . . . . . . . . . 152
5.1.1 Выбор кристально ясных имен . . . . . . . . . . . . . . . . . . . . . . . . . 153
5.1.2 Выбор простых в использовании типов данных  
и форматов  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.1.3 Выбор готовых к использованию данных  . . . . . . . . . . . . . . . . 157

5.2 Проектирование простых взаимодействий  . . . . . . . . . . . . . .159
5.2.1 Запрос простых входных данных . . . . . . . . . . . . . . . . . . . . . . .160
5.2.2 Выявление всех возможных ошибок . . . . . . . . . . . . . . . . . . . . . 162
5.2.3 Возвращение информативного сообщения об ошибке  . . . . . 163
5.2.4 Возвращение исчерпывающего сообщения об ошибке . . . . . .168
5.2.5 Возвращение информативного сообщения  
об успешном результате  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170

5.3 Проектирование простых потоков . . . . . . . . . . . . . . . . . . . . . . . 172
5.3.1 Построение простой цепочки целей  . . . . . . . . . . . . . . . . . . . .174
5.3.2 Предотвращение ошибок  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.3.3 Объединение целей . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
5.3.4 Проектирование потоков без сохранения состояния  . . . . .180

Содержание

6 

Проектирование предсказуемого API  . . . . . . . . . . . . . . . .183
6.1 Согласованность . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
6.1.1 Проектирование согласованных данных . . . . . . . . . . . . . . . . . 185
6.1.2 Проектирование согласованных целей  . . . . . . . . . . . . . . . . . .188
6.1.3 Четыре уровня согласованности . . . . . . . . . . . . . . . . . . . . . . .189
6.1.4  Копируя других: следование общепринятым  
практикам и соблюдение стандартов . . . . . . . . . . . . . . . . . .190
6.1.5 Согласованность – это сложно, и все нужно  
делать по-умному  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

6.2 Адаптируемость . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
6.2.1 Предоставление и принятие разных форматов . . . . . . . . . . 195
6.2.2 Интернационализация и локализация  . . . . . . . . . . . . . . . . . .199
6.2.3 Фильтрация, разбиение на страницы и сортировка  . . . . . . 202

6.3 Быть видимым  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
6.3.1 Предоставление метаданных  . . . . . . . . . . . . . . . . . . . . . . . . . 205
6.3.2 Создание гипермедиа-API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
6.3.3 Использование преимуществ протокола HTTP . . . . . . . . . . .210

7  

Проектирование лаконичного и хорошо  
организованного API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
7.1 
Организация API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
7.1.1 Организация данных  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
7.1.2 Организация ответных сообщений . . . . . . . . . . . . . . . . . . . . . 217
7.1.3 Организация целей . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219

7.2 
Определение размера API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
7.2.1 Выбор детализации данных  . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
7.2.2 Выбор детализации целей   . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
7.2.3 Выбор детализации API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229

Часть III.  Контекстное проектирование API  . 233
8 

Проектирование безопасного API . . . . . . . . . . . . . . . . . . . . .235
8.1 Обзор безопасности API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.1.1 Регистрация потребителя . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.1.2 Получение учетных данных для использования API . . . . . . . .238
8.1.3 Выполнение API-вызова  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
8.1.4 Проектирование API с точки зрения безопасности . . . . . . . 241

8.2 Разделение API на части для облегчения  
управления доступом . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.2.1 Определение гибких, но точных групп . . . . . . . . . . . . . . . . . . . 245
8.2.2 Определение простых, но менее детализированных групп. . 247
8.2.3 Выбор стратегии   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
8.2.4 Определение групп с помощью формата описания API  . . . . 251

8.3 Проектирование с учетом управления доступом . . . . . . . . .254

Содержание
11

8.3.1 Какие данные необходимы для управления доступом . . . . . .254
8.3.2 Адаптация дизайна при необходимости  . . . . . . . . . . . . . . . . 255

8.4 Обработка конфиденциальных данных  
и важных вещей  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
8.4.1 Обработка конфиденциальных данных . . . . . . . . . . . . . . . . . .258
8.4.2 Обработка конфиденциальных целей . . . . . . . . . . . . . . . . . . . 261
8.4.3 Проектирование безопасных сообщений об ошибках  . . . . . .264
8.4.4 Выявление проблем, связанных с архитектурой  
и протоколом . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

9 

Изменение дизайна API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
9.1 
Проектирование изменений API  . . . . . . . . . . . . . . . . . . . . . . . . 271
9.1.1 Избегая критических изменений в выходных данных  . . . . . . 272
9.1.2  Как избежать критических изменений  
во входных данных и параметрах  . . . . . . . . . . . . . . . . . . . . . . 277
9.1.3  Как избежать критических изменений в сообщениях  
об успехе или ошибках . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
9.1.4 Как избежать критических изменений в целях  
и потоках  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
9.1.5  Предотвращение нарушений в системе безопасности 
и критических изменений . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
9.1.6 Невидимый контракт интерфейса  . . . . . . . . . . . . . . . . . . . . 287
9.1.7 Критическое изменение – не всегда проблема . . . . . . . . . . . .288

9.2 
Управление версиями API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
9.2.1 Управление версиями API и реализации. . . . . . . . . . . . . . . . . .290
9.2.2  Выбор представления управления версиями API  
с точки зрения потребителя . . . . . . . . . . . . . . . . . . . . . . . . . . 292
9.2.3  Выбор детализации . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
9.2.4 Влияние управления версиями API за пределами  
проектирования . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

9.3 
Проектирование API с учетом расширяемости . . . . . . . . . . . 302
9.3.1 Проектирование расширяемых данных . . . . . . . . . . . . . . . . . . 302
9.3.2 Проектирование расширяемых взаимодействий  . . . . . . . . . 306
9.3.3 Проектирование расширяемых потоков  . . . . . . . . . . . . . . . . 307
9.3.4 Проектирование расширяемых API . . . . . . . . . . . . . . . . . . . . .308

10 

Проектирование эффективного API для сети  . . . . . .311
10.1 Обзор проблем передачи данных по сети . . . . . . . . . . . . . . . . 312
10.1.1 Подготовка сцены  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
10.1.2 Анализ проблем. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

10.2 Обеспечение эффективности передачи данных  
по сети на уровне протокола  . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
10.2.1 Активация сжатия и постоянных соединений  . . . . . . . . . . .320
10.2.2 Активация кеширования и условных запросов  . . . . . . . . . . . 321
10.2.3 Выбор политики кеширования   . . . . . . . . . . . . . . . . . . . . . . . . 325

Содержание

10.3  Обеспечение эффективности передачи данных  
по сети на уровне дизайна  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
10.3.1 Активация фильтрации . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
10.3.2 Выбор соответствующих данных для представлений  
списка  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
10.3.3 Агрегирование данных . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
10.3.4 Предложение разных представлений  . . . . . . . . . . . . . . . . . . .334
10.3.5 Активация расширения  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
10.3.6 Активация запросов  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
10.3.7 Предоставление более релевантных данных и целей  . . . . . .340
10.3.8 Создание разных слоев API  .  .  .  .  .  .  .  .  .  .  .  .  .  .343

11 

Проектирование API в контексте . . . . . . . . . . . . . . . . . . . .345
11.1 Адаптация передачи данных к целям  
и характеру данных . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
11.1.1 Управление длительными процессами  . . . . . . . . . . . . . . . . . . 347
11.1.2 Уведомление потребителей о событиях  . . . . . . . . . . . . . . . .349
11.1.3 Потоковая передача событий . . . . . . . . . . . . . . . . . . . . . . . . . 352
11.1.4 Обработка нескольких элементов  . . . . . . . . . . . . . . . . . . . . . 357

11.2 Соблюдение полного контекста  . . . . . . . . . . . . . . . . . . . . . . . . . 365
11.2.1 Знание существующих практик и ограничений  
потребителей  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
11.2.2 Тщательно учитываем ограничения поставщика  . . . . . . . .370

11.3 Выбор стиля API в соответствии с контекстом  . . . . . . . . . . . 373
11.3.1 Сравнение API на базе ресурсов, данных и функций. . . . . . . .374
11.3.2 За границами API на базе HTTP . . . . . . . . . . . . . . . . . . . . . . . .379

12 

Документирование API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
12.1 Создание справочной документации . . . . . . . . . . . . . . . . . . . .384
12.1.1 Документирование моделей данных . . . . . . . . . . . . . . . . . . . . 385
12.2.1 Документирование целей . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
12.1.3 Документирование безопасности . . . . . . . . . . . . . . . . . . . . . . 396
12.1.4 Обзор API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398
12.1.5  Генерирование документации из кода реализации:  
плюсы и минусы. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399

12.2 Создание руководства пользователя . . . . . . . . . . . . . . . . . . . . .400
12.2.1 Документирование вариантов использования  . . . . . . . . . . . 401
12.2.2 Документирование безопасности . . . . . . . . . . . . . . . . . . . . . .404
12.2.3 Предоставление обзора общепринятого поведения  
и принципов. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404
12.2.4 Мышление вне статической документации. . . . . . . . . . . . . .404

12.3 Предоставление адекватной информации  
разработчикам  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

12.4 Документирование изменений API  
и устаревшие функции . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .409

Содержание
13

13 

Развитие API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
13.1 Жизненный цикл API  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414
13.2 Создание руководства по проектированию API . . . . . . . . . . 415
13.2.1 Что включить в руководство по проектированию API  . . . . 416
13.2.2 Постоянное создание руководств . . . . . . . . . . . . . . . . . . . . . .420

13.3 Проверка API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
13.3.1 Оспаривание потребностей и их анализ  . . . . . . . . . . . . . . . .424
13.3.2 Линтирование  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
13.3.3 Проверка дизайна с точки зрения поставщика . . . . . . . . . . .430
13.3.4 Проверка дизайна с точки зрения потребителя . . . . . . . . . . 432
13.3.5 Проверка реализации  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

13.4 Общайтесь и делитесь информацией . . . . . . . . . . . . . . . . . . . . 435

Предисловие 

На протяжении более десяти лет для большинства разработчиков проектирование API всегда подразумевало архитектуру REST. Такая ситуация 
сложилась в связи с регулярным выходом книг и блогов об API, которые 
продвигают мировоззрение RESTful – и это порождает некую зацикленность на данном направлении, если не сказать догматизм. Эта книга знаменует появление руководств по проектированию API следующего поколения, которые помогут нам преодолеть ограничения, тормозившие 
более десяти лет. Практический подход к разработке API по-прежнему 
основывается на REST, но автор очень старался сформировать представление о разработке API в практических ситуациях за вычетом имеющихся догм.
Арно Лоре знакомит нас с основами проектирования API, которые 
легко можно найти в других отраслевых изданиях, и раскрывает тему 
просто и доступно, рассматривая широкий круг вопросов в удобной для 
читателя форме. Я знаком с Арно уже несколько лет и считаю его одним 
из немногих высокопрофессиональных специалистов, которые не только знают, как создавать API технически, но и понимают проблемы, связанные с их доставкой потребителю, и знают, в каких случаях API могут 
оказывать положительное или отрицательное влияние на опыт разработчика. Арно фокусируется не только на проектировании API, но и на 
предоставлении правильно спроектированного API целевой аудитории 
продуманным образом.
Я лично наблюдал, как Арно принимал самое активное участие в дискуссиях, касающихся API, по всему миру, извлекая из них все самое полезное для себя. Достаточно просмотреть его страницу в Twitter или 
перейти по хештегу, посвященному какому-нибудь популярному мероприятию, связанному с API, чтобы понять, о чем я говорю. Арно использует уникальный подход, слушая доклады представителей из индустрии 
API и обрабатывая информацию, которой они делятся, и затем освеща

Предисловие 
15

ет в Twitter важные моменты беседы, представляя сведения об 
API в удобном для восприятия формате. Я рад, что Арно свел 
накопленные им знания воедино и изложил в книге, продолжая не только оттачивать собственные навыки, но и делиться 
с другими людьми своими знаниями и уникальным подходом 
к проектированию API. Арно принадлежит к редкой породе 
API-аналитиков, которые заботятся о развитии темы: впитывают знания об API, усваивают их и распространяют в доступной 
форме, так что их становится действительно легко применить 
в мире бизнеса.
После того как, начиная с 2012 года, проектирование API 
стало набирать обороты и стала очевидной доминирующая 
роль спецификации OpenAPI (ранее известной как Swagger), 
Арно был одним из немногих экспертов в области API, которые усердно старались раскрыть потенциал этой спецификации, а также разрабатывали инновационные инструменты 
и визуализации, связанные со стандартом спецификации API 
с открытым исходным кодом – чтобы понять не только спецификацию, но и то, как она может реализовывать, представлять 
и даже организовывать многие принципы проектирования API, 
необходимые для достижения успеха. Понадобится много работать, прежде чем вы поймете, что OpenAPI – не только документация; большинство разработчиков API так и не проходят 
этот путь до конца. Арно понимает, что OpenAPI – это к тому 
же и основа проектирования API для любой платформы, что 
помогает определить каждую остановку на протяжении всего 
жизненного цикла API. Эта книга – первое руководство по проектированию API из тех, что я видел, в котором OpenAPI и проектирование API объединены так вдумчиво и эффективно, что 
многие разработчики почувствуют несомненную пользу чтения.
Потратьте время, чтобы понять, чем Арно делится с вами. Это 
книга не предназначена для беглого пролистывания, и она уж 
точно не из серии «прочитал и забыл». Это справочник. Руководство по переходу проектирования ваших API на новый уровень. Оно дает вам набор концепций API, с которыми вы знакомы, и предоставляет вам чертежи для создания «Тысячелетнего 
сокола» или даже «Звезды Смерти» (если, конечно, пожелаете) 
из набора строительных блоков API.
Рекомендую вам прочитать эту книгу, а затем отложить ее на 
месяц. Затем приступайте к созданию API и переходу от проектирования к фактическому развертыванию и общедоступности – и поделитесь своими знаниями с разработчиками. А пока 
ждете отзывов, сядьте и снова возьмитесь за книгу. Вы начнете 
понимать глубину и ценность знаний, которыми Арно делится с вами. Возвращайтесь к чтению до тех пор, пока вы не научитесь в полной мере создавать API – не идеальные образцы, 

Предисловие 

а именно тот API, который вам нужен, чтобы доcтучаться до потребителей, на которых вы рассчитываете повлиять.

 
— Кин Лейн, апологет API

От автора 

На протяжении своей карьеры я большей частью соединял программные блоки, используя различные технологии программных интерфейсов – начиная с простых файлов и баз данных и заканчивая удаленными 
программными интерфейсами на базе RPC, Corba, Java RMI, веб-сервисов SOAP и веб-API. В эти годы мне посчастливилось работать над разнородными распределенными системами, смешивая очень старую технологию мейнфреймов с современными облачными системами и всем, 
что находится посередине между ними. Мне также посчастливилось работать с обеими сторонами программных интерфейсов в различных 
контекстах. Я работал над IVR (Interactive Voice Response), веб-сайтами 
и мобильными приложениями, созданными поверх огромных систем 
сервис-ориентированной архитектуры. Я создавал закрытые и общедоступные веб-сервисы и веб-API для веб-приложений и приложений на 
стороне сервера. Все эти годы я много жаловался на ужасные программные интерфейсы – и попадал в ловушки, создавая точно такие же.
Шли годы, и технология развивалась, переходя от RPC к веб-сервисам SOAP и веб-API. Объединять программное обеспечение становилось все проще и проще с технической точки зрения. Но независимо от 
используемой технологии, я понял, что программный интерфейс – это 
гораздо больше, чем просто связующая система или побочный продукт 
программного проекта. После посещения первых конференций по API 
в 2014 году на API Days в Париже я понял, что есть множество других людей, которые, как и я, сражаются с API. Вот почему в 2015 году я начал вести блог API Handyman, а также стал участвовать в конференциях, посвященных API. Я хотел поделиться своим опытом с другими и помочь им 
избежать попадания в те же ловушки, в которые попал я. Когда я писал 
о веб-API и обсуждал их, это не только позволяло мне помогать другим, 
но и давало мне возможность узнать о них еще больше.

От автора 

После двух лет ведения блогов и выступлений на конференциях я пришел к решению написать книгу. Я хотел адресовать ее прежнему себе – 
тому, кто испытывал столько затруднений. К счастью, издательство 
Manning Publications искало человека, готового написать книгу о спецификации OpenAPI, формате описания API (об этом мы поговорим в главе 
4). Я воспользовался шансом, предложив свою книгу Design of Everyday 
APIs, и ее приняли. На это название меня вдохновила книга «Дизайн 
привычных вещей» Дона Нормана (MIT Press, 1998) – вам обязательно 
стоит прочитать ее. Позже первоначальный заголовок заменили более 
простым, The Design of Web APIs. Должен признать, что он мне нравится больше; теперь у меня нет ощущения, что я покушаюсь на лавры Дона 
Нормана.
Поначалу в книге освещалось проектирование повседневных вещей 
+ API + REST в сравнении с gRPC в сравнении с GraphQL. Усвоить все это 
было бы довольно трудно, но я хотел, чтобы изложенные в книге принципы можно было использовать для любого типа API. Месяц за месяцем содержание совершенствовалось, в результате чего получилась книга, которая сейчас называется The Design of Web APIs («Проектирование 
веб-API»). Я решил сосредоточиться на REST API и использовать их в качестве примера для изучения принципов проектирования веб- и удаленных API, что выходит за рамки простого проектирования API. Если 
бы такая книга попалась в прежние времена, я был бы очень рад ее изучить; надеюсь, вам тоже понравится!