Хороший web API распознается не по красивому URL, а по тому, насколько мало скрытых знаний он требует от клиента.
Для реального проектирования глава помогает увидеть, как URI, link relations, URI templates и общие правила именования снижают когнитивную нагрузку на потребителей и делают интерфейс предсказуемее.
Для интервью и инженерных разборов она полезна тем, что помогает обсуждать API-consistency через consumer confusion, reuse и ясность semantics, а не через вкусовые споры о стиле.
Практическая польза главы
Практика проектирования
Проектируйте URI и link-relations так, чтобы клиенту было проще использовать API без hidden knowledge.
Качество решений
Делайте API-consistency измеримой через style rules и reusable design patterns.
Interview articulation
Показывайте, как API UX влияет на стоимость интеграции и time-to-market партнеров.
Failure framing
Снижайте риск consumer confusion из-за непоследовательных naming и semantics.
Источник
Обзор книги
Оригинальный обзор Александра Поломодова на 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 требует значительных усилий проектирования.
Связанные главы
- Continuous API Management (short summary) - Операционный контур API-as-a-Product: lifecycle, governance и управление эволюцией контрактов.
- API Design Patterns (short summary) - Паттерны контрактного дизайна и правила обратной совместимости для долгоживущих API.
- API для людей: как сделать интерфейс понятным - DX-подход к проектированию API: понятность, предсказуемость и снижение порога входа для клиентов.
- API Gateway - Практическая реализация маршрутизации, edge-policy и контроля трафика для web API.
- Паттерны межсервисной коммуникации - Как качество API-контрактов влияет на устойчивость и стоимость межсервисных интеграций.
- API Security Patterns - Безопасность web API: аутентификация, авторизация, threat-модели и policy enforcement.
- Learning GraphQL (short summary) - Сравнение REST-ориентированного дизайна с GraphQL-подходом и компромиссами клиентского API-слоя.