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

Обложка
Оглавление
Содержание
Часть I.
Основы разработки API
Что такоеразработка API
Разработка API для пользователей
Разработка программного интерфейса
Описание API с помощью формата описания
Часть 2.
Практичнаяразработка API
Разработка простого API
Разработка предсказуемого API
Разработкалаконичного и хорошо организованного API
Часть 3.
Контекстный дизайн API
Разработка безопасного API
Изменение дизайна API
Разработка эффективного API для сети
Разработка API в контексте
Документирование API
Развитие API
Предисловие
От автора
Благодарности
Об этой книге
Об авторе
Об иллюстрации на обложке
Основы разработки API
Что такоеразработка API
1.1. Что такое API?
1.1.1. API – это веб-интерфейс для программного обеспечения
1.1.2. API превращают программное обеспечение в детали конструктора LEGO®
1.2. Чем важна разработка API
1.2.1. Открытый или закрытый API – это интерфейс для других разработчиков
1.2.2 API создается, для того чтобы скрыть реализацию
1.2.3. Страшные последствия плохо разработанных API
1.3. Элементы разработки API
1.3.1 Изучение принципов, выходящих за рамки разработки программного интерфейса
1.3.2 Изучение всех аспектов проектирования API
Разработка API для пользователей
2.1 Правильная точка зрения для разработки повседневных пользовательских интерфейсов
2.1.1 Когда вы фокусируетесь на том, как все работает, это приводит к возникновению сложных интерфейсов
2.1.2 Когда вы фокусируетесь на том, что могут делать пользователи, это приводит к появлению простых интерфейсов
2.2 Разработка интерфейсов программного обеспечения
2.2.1 API как панель управления программным обеспечением
2.2.2 Ориентация на точку зрения потребителя для созданияпростых API
2.3 Определение целей API
2.3.1 Отвечая на вопросы «что?» и «как?»
2.3.2 Определение входных и выходных данных
2.3.3 Выявляем недостающие цели
2.3.4 Идентификация всех пользователей
2.3.5 Использование таблицы целей API
2.4 Избегаем точки зрения поставщика при разработке API
2.4.1 Как избежать влияния данных
2.4.2 Как избежать влияния кода и бизнес-логики
2.4.3 Как избежать влияния архитектуры программного обеспечения
2.4.4 Как избежать влияния организации, где работают люди
2.4.5 Определение точки зрения поставщика в таблице целей API
Разработка программного интерфейса
3.1 Знакомство с REST API
3.1.1 Анализ вызова REST API
3.1.2 Базовые принципы HTTP
3.1.3 Базовые принципы REST API
3.2 Перенос целей в REST API
3.2.1 Идентификация ресурсов и их связей с таблицей целей API
3.2.2 Идентификация действий, их параметров и результатов с помощью таблицы целей API
3.2.3 Представление ресурсов с помощью путей
3.2.4 Представление действий с помощью протокола HTTP
3.2.5 REST API и шпаргалка по HTTP
3.3 Разработка данных API
3.3.1 Разработка концепций
3.3.2 Разработка ответов от концепций
3.3.3 Разработка параметров из концепций или ответов
3.3.4 Проверка параметров источника данных
3.3.5 Проектирование других параметров
3.4 Достижение баланса при решении проблем разработки
3.4.1 Примеры компромисса
3.4.2 Баланс между удобством для пользователя и соответствием
3.5 Почему REST важен при разработке любого API
3.5.1 Знакомство с архитектурным стилем REST
3.5.2 Влияние ограничений REST на разработку API
Описание API с помощью формата описания
4.1 Что такое формат описания API?
4.1.1 Спецификация OpenAPI (OAS)
4.1.2 Зачем использовать формат описания API?
4.1.3 Когда использовать формат описания API
4.2 Описание ресурсов и действий API с помощью OAS
4.2.1 Создание документа OAS
4.2.2 Описание ресурса
4.2.3 Описание операций в ресурсе
4.3 Описание данных API с помощью OpenAPI и JSON Schema
4.3.1 Описание параметров запроса
4.3.2 Описание данных с помощью JSON Schema
4.3.3 Описание ответов
4.3.4 Описание параметров тела
4.4 Эффективное описание API с помощью OAS
4.4.1 Повторное использование компонентов
4.4.2 Описание параметров пути
Практичнаяразработка API
Разработка простого API
5.1 Разработка простых представлений
5.1.1 Выбор кристально ясных имен
5.1.2 Выбор простых в использовании типов данных и форматов
5.1.3 Выбор готовых к использованию данных
5.2 Проектирование простых взаимодействий
5.2.1 Запрос простых входных данных
5.2.2 Выявление всех возможных ошибок
5.2.3 Возвращение информативного сообщения об ошибке
5.2.4 Возвращение исчерпывающего сообщения об ошибке
5.2.5 Возвращение информативного сообщения об успешном результате
5.3 Проектирование простых потоков
5.3.1 Построение простой цепочки целей
5.3.2 Предотвращение ошибок
5.3.3 Объединение целей
5.3.4 Проектирование потоков без сохранения состояния
Разработка предсказуемого API
6.1 Согласованность
6.1.1 Разработка согласованных данных
6.1.2 Разработка согласованных целей
6.1.3 Четыре уровня согласованности
6.1.4 Копируя других: следование общепринятым практикам и соблюдение стандартов
6.1.5 Согласованность – это сложно, и все нужно делать по-умному
6.2 Адаптируемость
6.2.1 Предоставление и принятие разных форматов
6.2.2 Интернационализация и локализация
6.2.3 Фильтрация, разбиение на страницы и сортировка
6.3 Быть видимым
6.3.1 Предоставление метаданных
6.3.2 Создание гипермедийных API
6.3.3 Использование преимуществ протокола HTTP
Разработкалаконичного и хорошо организованного API
7.1 Организация API
7.1.1 Организация данных
7.1.2 Организация ответных сообщений
7.1.3 Организация целей
7.2 Определение размера API
7.2.1 Выбор детализации данных
7.2.2 Выбор детализации целей
7.2.3 Выбор детализации API
Контекстный дизайн API
Разработка безопасного API
8.1 Обзор безопасности API
8.1.1 Регистрация потребителя
8.1.2 Получение учетных данных для использования API
8.1.3 Выполнение API-вызова
8.1.4 Разработка API с точки зрения безопасности
8.2 Разделение API на части для облегчения управления доступом
8.2.1 Определение гибких, но точных групп
8.2.2 Определение простых, но менее детализированных групп
8.2.3 Выбор стратегии
8.2.4 Определение групп с помощью формата описания API
8.3 Разработка с учетом управления доступом
8.3.1 Какие данные необходимы для управления доступом
8.3.2 Адаптация дизайна при необходимости
8.4 Обработка конфиденциальных данных и важных вещей
8.4.1 Обработка конфиденциальных данных
8.4.2 Обработка конфиденциальных целей
8.4.3 Разработка безопасных сообщений об ошибках
8.4.4 Выявление проблем, связанных с архитектурой и протоколом
Изменение дизайна API
9.1 Проектирование изменений API
9.1.1 Избегая критических изменений в выходных данных
9.1.2 Как избежать критических изменений во входных данных и параметрах
9.1.3 Как избежать критических изменений в сообщениях об успехе или ошибках
9.1.4 Как избежать критических изменений в целях и потоках
9.1.5 Предотвращение нарушений в системе безопасности и критических изменений
9.1.6 Невидимый контракт интерфейса
9.1.7 Критическое изменение – не всегда проблема
9.2 Управление версиями API
9.2.1 Управление версиями API и реализации
9.2.2 Выбор представления управления версиями API с точки зрения потребителя
9.2.3  Выбор детализации
9.2.4 Влияние управления версиями API за пределами разработки
9.3 Разработка API с учетом расширяемости
9.3.1 Разработка расширяемых данных
9.3.2 Проектирование расширяемых взаимодействий
9.3.3 Проектирование расширяемых потоков
9.3.4 Разработка расширяемых API
Разработка эффективного API для сети
10.1 Обзор проблем передачи данных по сети
10.1.1 Подготовка сцены
10.1.2 Анализ проблем
10.2 Обеспечение эффективности передачи данных по сети на уровне протокола
10.2.1 Активация сжатия и постоянных соединений
10.2.2 Активация кеширования и условных запросов
10.2.3 Выбор политики кеширования
10.3 Обеспечение эффективности передачи данных по сети на уровне дизайна
10.3.1 Активация фильтрации
10.3.2 Выбор соответствующих данных для представлений списка
10.3.3 Агрегирование данных
10.3.4 Предложение разных представлений
10.3.5 Активация расширения
10.3.6 Активация запросов
10.3.7 Предоставление более релевантных данных и целей
10.3.8 Создание разных слоев API
Разработка API в контексте
11.1 Адаптация передачи данных к целям и характеру данных
11.1.1 Управление длительными процессами
11.1.2 Уведомление потребителей о событиях
11.1.3 Потоковая передача событий
11.1.4 Обработка нескольких элементов
11.2 Соблюдение полного контекста
11.2.1 Знание существующих практик и ограничений потребителей
11.2.2 Тщательно учитываем ограничения поставщика
11.3 Выбор стиля API в соответствии с контекстом
11.3.1 Сравнение API на базе ресурсов, данных и функций
11.3.2 За границами API на базе HTTP
Документирование API
12.1 Создание справочной документации
12.1.1 Документирование моделей данных
12.2.1 Документирование целей
12.1.3 Документирование безопасности
12.1.4 Обзор API
12.1.5 Генерирование документации из кода реализации: плюсы и минусы
12.2 Создание руководства пользователя
12.2.1 Документирование вариантов использования
12.2.2 Документирование безопасности
12.2.3 Предоставление обзора общепринятого поведения и принципов
12.2.4 Мышление вне статической документации
12.3 Предоставление адекватной информации разработчикам
12.4 Документирование изменений API и устаревшие функции
Развитие API
13.1 Жизненный цикл API
13.2 Создание руководства по разработке API
13.2.1 Что включить в руководство по разработке API
13.2.2 Постоянное создание руководств
13.3 Проверка API
13.3.1 Оспаривание потребностей и их анализ
13.3.2 Линтирование
13.3.3 Проверка дизайна с точки зрения поставщика
13.3.4 Проверка дизайна с точки зрения потребителя
13.3.5 Проверка реализации
13.4 Общайтесь и делитесь информацией