Источник
Обзор книги
Оригинальный обзор Александра Поломодова на tellmeabout.tech
Web API Design: The Missing Link
Авторы: Brian Mulloy
Издательство: Apigee (Google Cloud)
Объём: ~60 страниц
Практическое руководство от Apigee: RESTful дизайн, ссылки вместо ID, URI Templates, URL design и HATEOAS.
ОригиналКлючевые принципы
Связанная тема
Continuous API Management
Глубокий разбор API Lifecycle и Governance
Авторы предлагают подход к проектированию API, ориентированный на данные:
RESTful стиль
Использование архитектурного стиля REST с акцентом на простоту и легкость понимания.
Ссылки вместо ID
Акцент на использовании ссылок на ресурсы вместо просто идентификаторов — главная идея книги.
HTTP + RFC
REST в паре с HTTP, активное использование рекомендаций из стандартов RFC.
Стандарт
RFC 6570
URI Template — спецификация для выражения URI через переменные
URI Templates
Использование концепций URI templates из RFC 6570 для предсказуемых URL.
"Совершенство достигается не тогда, когда уже ничего нельзя добавить, а тогда, когда ничего нельзя убрать"
— Антуан де Сент-Экзюпери
Элементы дизайна API
Авторы выделяют ключевые элементы, которые составляют дизайн API:
Представление ресурсов
Определение полей и формата ссылок на связанные ресурсы
HTTP заголовки
Использование стандартных и кастомных заголовков
URL и URI Templates
Интерфейс для выполнения запросов и нахождения ресурсов
Поведение клиентов
Кэширование в DNS, retries, устойчивость к новым полям в JSON
Дизайн URL
Практика
API Gateway
Паттерны маршрутизации и обработки запросов
Рекомендации по проектированию URL для RESTful API:
Хорошо
- Существительные в URL
- Множественное число для коллекций
- Свойства в пути route
- Взаимоотношения в URL
Плохо
- Глаголы в URL
- Функции типа convert/translate
- Query параметры вместо path
- Непредсказуемые структуры
Пример: два вида ссылок на сущность
Query по уникальному параметру:
/persons?email=john@example.com
Постоянный permalink по UUID:
/persons/550e8400-e29b-41d4-a716-446655440000
* Это позволяет при изменении email не менять permalink
Дизайн Query URL
Авторы рекомендуют размещать свойства фильтрации в пути, а не в GET-параметрах:
✓ Рекомендуется
/persons/{personId}/dogsВзаимоотношения выражены в URL
✗ Не рекомендуется
/search?type=Dog&owner={personId}Скрытые взаимоотношения
"The key insight is that the URL should identify the resource in the response, not the processing algorithm that calculates the response"
Почему ссылки важны
Главная идея книги — использовать ссылки на ресурсы вместо простых идентификаторов:
Вместо ID
{
"id": "123",
"name": "Rex",
"ownerId": "456"
}Ссылки на ресурсы
{
"id": "123",
"name": "Rex",
"owner": "/persons/456"
}Ссылки делают API самодокументируемым и упрощают навигацию по связанным ресурсам, даже если клиент не знает URI templates.
Содержание книги
Книга содержит 12 разделов, которые охватывают все аспекты проектирования Web API:
Главный вывод
"HTTP provides a standard API for the basic CRUD portion of every web API, but it does not have as much to say about how queries over the data are expressed. This is why a significant amount of design effort typically goes into the design of URLs that express queries"
HTTP даёт стандартный интерфейс для CRUD операций, но дизайн query URL требует значительных усилий проектирования.