Паттерны проектирования API: 16+

API представляют собой контракты, которые определяют принципы взаимодействия приложений, сервисов и компонентов. Паттерны проектирования API — это набор лучших практик, спецификаций и стандартов, обеспечивающих простоту и надежность их использования для разработчиков. Книга объединяет и объясняет наиболее важные паттерны, используемые сообществом разработчиков API и экспертами Google. Паттерны проектирования API определяют набор принципов для разработки внутренних и публичных API. Джей Джей Гивакс, будучи специалистом из Google, рассказывает о паттернах, которые обеспечат вашим API согласованность, масштабируемость и гибкость. Вы узнаете, как улучшить дизайн самых распространенных API и как действовать в сложных пограничных случаях. Понятные иллюстрации, актуальные примеры и подробные сценарии позволят тщательно разобраться в каждом паттерне. Предисловие Вступление Благодарности О книге Для кого эта книга Структура издания О коде Онлайн-ресурсы Об авторе Иллюстрация на обложке От издательства Часть I. Введение Глава 1. Знакомство с API 1.1. Что такое веб-API 1.2. Почему API важны 1.3. Что значит ресурсно-ориентированные API 1.4. Что делает API «хорошим» 1.4.1. Функциональность 1.4.2. Выразительность 1.4.3. Простота 1.4.4. Предсказуемость Резюме Глава 2. Знакомство с паттернами проектирования API 2.1. Что такое паттерны проектирования API 2.2. Чем важны паттерны проектирования API 2.3. Анатомия паттерна проектирования API 2.3.1. Имя и аннотация 2.3.2. Зачем он нужен 2.3.3. Обзор 2.3.4. Реализация 2.3.5. Компромиссы 2.4. Практическое исследование: Twapi, Twitter-подобное API 2.4.1. Обзор 2.4.2. Создание списка сообщений 2.4.3. Экспорт данных Резюме Часть II. Принципы проектирования Глава 3. Именование 3.1. Почему важны имена 3.2. Что делает имя «хорошим» 3.2.1. Выразительность 3.2.2. Простота 3.2.3. Предсказуемость 3.3. Язык, грамматика и синтаксис 3.3.1. Язык 3.3.2. Грамматика 3.3.3. Синтаксис 3.4. Контекст 3.5. Типы данных и единицы измерения 3.6. Практическое исследование: что происходит при выборе плохих имен 3.7. Упражнения Резюме Глава 4. Состав и иерархия ресурсов 4.1. Что такое схема ресурсов 4.1.1. Типы связей 4.1.2. Блок-схемы связей между сущностями 4.2. Выбор правильных связей 4.2.1. Нужна ли вообще связь 4.2.2. Ссылки или встроенные данные 4.2.3. Иерархия 4.3. Антипаттерны 4.3.1. Ресурсы для всего 4.3.2. Глубокие иерархии 4.3.3. Встраивание всего 4.4. Упражнения Резюме Глава 5. Типы данных и значения по умолчанию 5.1. Знакомство с типами данных 5.1.1. Отсутствующее значение и значение null 5.2. Логический тип 5.3. Числа 5.3.1. Границы 5.3.2. Значения по умолчанию 5.3.3. Сериализация 5.4. Строки 5.4.1. Границы 5.4.2. Значения по умолчанию 5.4.3. Сериализация 5.5. Перечисления 5.6. Списки 5.6.1. Атомарность 5.6.2. Границы 5.6.3. Значения по умолчанию 5.7. Карты 5.7.1. Границы 5.7.2. Предустановленные значения 5.8. Упражнения Резюме Часть III. Основы Глава 6. Идентификация ресурсов 6.1. Что такое идентификатор 6.2. Что делает идентификатор хорошим 6.2.1. Простота использования 6.2.2. Уникальность 6.2.3. Постоянство 6.2.4. Быстрая и легкая генерация 6.2.5. Непредсказуемость 6.2.6. Читабельность, передача и возможность проверки 6.2.7. Информационная плотность 6.3. Как выглядит хороший идентификатор 6.3.1. Тип данных 6.3.2. Набор символов 6.3.3. Формат идентификатора 6.3.4. Контрольные суммы 6.3.5. Тип ресурса 6.3.6. Иерархия и область уникальности 6.4. Реализация 6.4.1. Размер 6.4.2. Генерация 6.4.3. Отметка об удалении (Tomb-stoning) 6.4.4. Контрольная сумма 6.4.5. Хранилище базы данных 6.5. UUID 6.6. Упражнения Резюме Глава 7. Стандартные методы 7.1. Зачем это нужно 7.2. Обзор 7.3. Реализация 7.3.1. Какие методы должны поддерживаться 7.3.2. Идемпотентность и побочные эффекты 7.3.3. Метод Get 7.3.4. Метод List 7.3.5. Метод Create 7.3.6. Метод Update 7.3.7. Метод Delete 7.3.8. Метод Replace 7.3.9. Итоговое определение API 7.4. Компромиссы 7.5. Упражнения Резюме Глава 8. Частичное обновление и извлечение 8.1. Зачем это нужно 8.1.1. Частичное извлечение 8.1.2. Частичное обновление 8.2. Обзор 8.3. Реализация 8.3.1. Передача 8.3.2. Карты и вложенные интерфейсы 8.3.3. Повторяющиеся поля 8.3.4. Значения по умолчанию 8.3.5. Неявные маски полей 8.3.6. Обновление динамических структур данных 8.3.7. Недействительные поля 8.3.8. Итоговое определение API 8.4. Компромиссы 8.4.1. Универсальная поддержка 8.4.2. Альтернативные реализации 8.5. Упражнения Резюме Глава 9. Пользовательские методы 9.1. Зачем это нужно 9.1.1. Почему бы просто не задействовать стандартные методы 9.2. Обзор 9.3. Реализация 9.3.1. Побочные эффекты 9.3.2. Ресурсы или коллекции 9.3.3. Пользовательские методы без сохранения состояния 9.3.4. Итоговое определение API 9.4. Компромиссы 9.5. Упражнения Резюме Глава 10. Длительные операции 10.1. Зачем это нужно 10.2. Обзор 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. Инспектирование операций 10.3.9. Продолжительность хранения 10.3.10. Итоговое определение API 10.4. Компромиссы 10.5. Упражнения Резюме Глава 11. Перезапускаемые задачи 11.1. Зачем это нужно 11.2. Обзор 11.3. Реализация 11.3.1. Ресурсы Job 11.3.2. Пользовательский метод Run 11.3.3. Ресурсы выполнения задачи 11.3.4. Итоговое определение API 11.4. Компромиссы 11.5. Упражнения Резюме Часть IV. Связи ресурсов Глава 12. Подресурсы-одиночки 12.1. Зачем это нужно 12.1.1. Почему нужно использовать подресурс-одиночку? 12.2. Обзор 12.3. Реализация 12.3.1. Стандартные методы 12.3.2. Сброс 12.3.3. Иерархия 12.3.4. Итоговое определение API 12.4. Компромиссы 12.4.1. Атомарность выполнения 12.4.2. Ровно один подресурс 12.5. Упражнения Резюме Глава 13. Перекрестные ссылки 13.1. Зачем это нужно 13.2. Обзор 13.3. Реализация 13.3.1. Имя ссылочного поля 13.3.2. Целостность данных 13.3.3. Значение или ссылка 13.3.4. Итоговое определение API 13.4. Компромиссы 13.5. Упражнения Резюме Глава 14. Ассоциирующие ресурсы 14.1. Зачем это нужно 14.2. Обзор 14.2.1. Ассоциирующие методы-псевдонимы 14.3. Реализация 14.3.1. Выбор имени для ассоциирующего ресурса 14.3.2. Поведение стандартных методов 14.3.3. Уникальность 14.3.4. Поля только для чтения 14.3.5. Ассоциирующие методы-псевдонимы 14.3.6. Ссылочная целостность 14.3.7. Итоговое определение API 14.4. Компромиссы 14.4.1. Сложность 14.4.2. Отделенность ассоциирующих ресурсов 14.5. Упражнения Резюме Глава 15. Пользовательские методы Add и Remove 15.1. Зачем это нужно 15.2. Обзор 15.3. Реализация 15.3.1. Вывод списка связанных ресурсов 15.3.2. Целостность данных 15.3.3. Итоговое определение API 15.4. Компромиссы 15.4.1. Подчинительная связь 15.4.2. Метаданные о связи 15.5. Упражнения Резюме Глава 16. Полиморфизм 16.1. Зачем это нужно 16.2. Обзор 16.3. Реализация 16.3.1. Когда использовать полиморфные ресурсы 16.3.2. Полиморфная структура 16.3.3. Полиморфное поведение 16.3.4. Почему не стоить использовать полиморфные методы 16.3.5. Итоговое определение API 16.4. Компромиссы 16.5. Упражнения Резюме Часть V. Коллективные операции Глава 17. Копирование и перемещение 17.1. Зачем это нужно 17.2. Обзор 17.3. Реализация 17.3.1. Идентификаторы 17.3.2. Дочерние ресурсы 17.3.3. Связанные ресурсы 17.3.4. Внешние данные 17.3.5. Наследуемые метаданные 17.3.6. Атомарность 17.3.7. Итоговое определение API 17.4. Компромиссы 17.5. Упражнения Резюме Глава 18. Пакетные операции 18.1. Зачем это нужно 18.2. Обзор 18.3. Реализация 18.3.1. Атомарность 18.3.2. Операции над коллекцией 18.3.3. Упорядочивание результатов 18.3.4. Общие поля 18.3.5. Оперирование с разными родителями 18.3.6. Пакетный метод Get 18.3.7. Пакетный метод Delete 18.3.8. Пакетный метод Create 18.3.9. Пакетный метод Update 18.3.10. Итоговое определение API 18.4. Компромиссы 18.5. Упражнения Резюме Глава 19. Удаление на основе критерия 19.1. Зачем это нужно 19.2. Обзор 19.3. Реализация 19.3.1. Фильтрация результатов 19.3.2. По умолчанию только проверка 19.3.3. Подсчет результатов 19.3.4. Выборка результатов 19.3.5. Согласованность 19.3.6. Итоговое определение API 19.4. Компромиссы 19.5. Упражнения Резюме Глава 20. Анонимная запись 20.1. Зачем это нужно 20.2. Обзор 20.3. Реализация 20.3.1. Согласованность 20.3.2. Итоговое определение API 20.4. Компромиссы 20.5. Упражнения Резюме Глава 21. Пагинация 21.1. Зачем это нужно 21.2. Обзор 21.3. Реализация 21.3.1. Размер страницы 21.3.2. Маркеры страниц 21.3.3. Общее количество 21.3.4. Пагинация внутри ресурсов 21.3.5. Итоговое определение API 21.4. Компромиссы 21.4.1. Двунаправленная пагинация 21.4.2. Произвольный выбор окна 21.5. Антипаттерн: смещения и границы 21.6. Упражнения Резюме Глава 22. Фильтрация 22.1. Зачем это нужно 22.2. Обзор 22.3. Реализация 22.3.1. Структура 22.3.2. Синтаксис фильтра и поведение 22.3.3. Итоговое определение API 22.4. Компромиссы 22.5. Упражнения Резюме Глава 23. Импорт и экспорт 23.1. Зачем это нужно 23.2. Обзор 23.3. Реализация 23.3.1. Методы Import и Export 23.3.2. Взаимодействие с системами хранения данных 23.3.3. Преобразование между ресурсами и байтами 23.3.4. Согласованность 23.3.5. Идентификаторы и коллизии 23.3.6. Обработка связанных ресурсов 23.3.7. Сбои и повторы 23.3.8. Фильтрация и маски полей 23.3.9. Итоговое определение API 23.4. Компромиссы 23.5. Упражнения Резюме Часть VI. Безопасность Глава 24. Версионирование и совместимость 24.1. Зачем это нужно 24.2. Обзор 24.2.1. Что такое совместимость 24.2.2. Определение обратной совместимости 24.3. Реализация 24.3.1. Вечная стабильность 24.3.2. Подвижная нестабильность 24.3.3. Семантическое версионирование 24.4. Компромиссы 24.4.1. Детализация или простота? 24.4.2. Стабильность или новая функциональность? 24.4.3. Удовлетворенность или универсальность? 24.5. Упражнение Резюме Глава 25. Мягкое удаление 25.1. Зачем это нужно 25.2. Обзор 25.3. Реализация 25.3.1. Обозначение удаления 25.3.2. Изменение стандартных методов 25.3.3. Метод Undelete 25.3.4. Метод Expunge 25.3.5. Сроки хранения 25.3.6. Ссылочная целостность 25.3.7. Влияние на другие методы 25.3.8. Добавление мягкого удаления для разных версий 25.3.9. Итоговое определение API 25.4. Компромиссы 25.5. Упражнения Резюме Глава 26. Повтор запросов 26.1. Зачем это нужно 26.2. Обзор 26.3. Реализация 26.3.1. Идентификатор запроса 26.3.2. Кэширование ответа 26.3.3. Согласованность 26.3.4. Коллизии ID запросов 26.3.5. Срок действия кэша 26.3.6. Итоговое определение API 26.4. Компромиссы 26.5. Упражнения Резюме Глава 27. Валидация запросов 27.1. Зачем это нужно 27.2. Обзор 27.3. Реализация 27.3.1. Внешние зависимости 27.3.2. Особые побочные эффекты 27.3.3. Итоговое определение API 27.4. Компромиссы 27.5. Упражнения Резюме Глава 28. Ревизии ресурсов 28.1. Зачем это нужно 28.2. Обзор 28.3. Реализация 28.3.1. Идентификаторы ревизий 28.3.2. Создание ревизий 28.3.3. Извлечение конкретных ревизий 28.3.4. Перечисление ревизий 28.3.5. Восстановление прежней ревизии 28.3.6. Удаление ревизий 28.3.7. Обработка дочерних ресурсов 28.3.8. Итоговое определение API 28.4. Компромиссы 28.5. Упражнения Резюме Глава 29. Повтор запросов 29.1. Зачем это нужно 29.2. Обзор 29.2.1. Интервал повторов на стороне клиента 29.2.2. Интервал повторов, определяемый сервером 29.3. Реализация 29.3.1. Допустимость повтора 29.3.2. Экспоненциальная выдержка 29.3.3. Повторить через 29.3.4. Итоговое определение API 29.4. Компромиссы 29.5. Упражнения Резюме Глава 30. Аутентификация запросов 30.1. Зачем это нужно 30.1.1. Источник 30.1.2. Целостность 30.1.3. Невозможность отказа 30.2. Обзор 30.3. Реализация 30.3.1. Генерация учетных данных 30.3.2. Регистрация и обмен учетными данными 30.3.3. Генерация и верификация сырых подписей 30.3.4. Цифровой отпечаток для запроса 30.3.5. Добавление подписи 30.3.6. Аутентификация запросов 30.3.7. Итоговое определение API 30.4. Компромиссы 30.5. Упражнения Резюме