Проектирование веб-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