Проектирование веб-API
Покупка
Тематика:
Программирование и алгоритмизация
Издательство:
ДМК Пресс
Автор:
Лоре Арно
Перевод:
Беликов Дмитрий Анатольевич
Год издания: 2020
Кол-во страниц: 440
Дополнительно
Вид издания:
Практическое пособие
Уровень образования:
ВО - Магистратура
ISBN: 978-5-97060-861-6
Артикул: 748356.01.99
Доступ онлайн
В корзину
Книга, написанная с учетом многолетнего опыта автора в разработке API, научит вас, как собирать требования, как найти баланс между техническими и бизнес-целями и как принимать во внимание запросы потребителя. Рассматриваются основные характеристики API, принципы его изменения, документирования и проверки. Эффективные методы разработки проиллюстрированы множеством интересных примеров. Рассматриваются основные характеристики API, принципы его изменения, документирования и проверки. Эффективные методы разработки проиллюстрированы множеством интересных примеров.
Издание предназначено для разработчиков, обладающих минимальным опытом в создании и использовании API-интерфейсов.
Тематика:
ББК:
УДК:
ОКСО:
- ВО - Бакалавриат
- 09.03.01: Информатика и вычислительная техника
- 09.03.02: Информационные системы и технологии
- 09.03.03: Прикладная информатика
- 09.03.04: Программная инженерия
ГРНТИ:
Скопировать запись
Фрагмент текстового слоя документа размещен для индексирующих роботов.
Для полноценной работы с документом, пожалуйста, перейдите в
ридер.
Интернет-магазин: 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. Если бы такая книга попалась в прежние времена, я был бы очень рад ее изучить; надеюсь, вам тоже понравится!
Доступ онлайн
В корзину