Хороший Web API узнаётся не по красивому URL, а по тому, насколько мало скрытых знаний он требует от клиента.
Для реального проектирования глава показывает, как дизайн URI, типы ссылок, шаблоны URI и общие правила именования снижают когнитивную нагрузку на потребителей.
Для интервью и инженерных разборов она помогает обсуждать согласованность API через путаницу клиентов, повторное использование решений и ясность поведения, а не через вкусовые споры о стиле.
Практическая польза главы
Практика проектирования
Проектируйте URI и типы ссылок так, чтобы клиенту не приходилось знать внутренние правила сервера.
Качество решений
Делайте согласованность API измеримой через правила стиля и повторяемые проектные решения.
Аргументация на интервью
Показывайте, как удобство API влияет на стоимость интеграции и скорость выхода партнёров.
Анализ отказов
Снижайте риск путаницы у потребителей из-за непоследовательных названий и поведения.
Источник
Обзор книги
Оригинальный обзор Александра Поломодова на tellmeabout.tech
Web API Design: The Missing Link
Авторы: Brian Mulloy
Издательство: Apigee (Google Cloud)
Объём: ~60 страниц
Практическое руководство Apigee по дизайну Web API: ссылки на ресурсы, HTTP-семантика, шаблоны URI, HATEOAS, URL-дизайн и удобство потребления API.
В этой главе важнее красоты адресов само по себе: книга связывает , , HTTP-семантику, предсказуемые URL и поведение в один язык проектирования.
Ключевые принципы
Связанная тема
Continuous API Management
Жизненный цикл API, управление контрактами и безопасная эволюция интерфейсов
Авторы предлагают проектировать Web API от ресурсов, ссылок и поведения клиента:
REST и HTTP-семантика
API строится вокруг ресурсов, стандартных методов и понятной , а не вокруг случайных операций в стиле .
Ссылки вместо голых идентификаторов
Главная идея книги: возвращать , чтобы клиент видел, куда можно перейти дальше.
HTTP и стандарты
Дизайн опирается на HTTP, RFC-документы и устойчивый , а не на локальные договорённости команды.
Стандарт
RFC 6570
Спецификация шаблонов URI для адресов с переменными
Шаблоны URI
из RFC 6570 помогают описывать адреса с переменными и сохранять предсказуемую структуру URL.
Хороший API становится проще не тогда, когда в него добавили ещё один удобный адрес, а когда из него убрали лишние исключения, скрытые правила и неоднозначные адреса.
Элементы дизайна API
Книга раскладывает дизайн Web API на несколько решений, которые клиент ощущает каждый день:
Представление ресурсов
Поля, вложенность и формат должны быть стабильными для клиентов.
Заголовки HTTP
задают кэширование, типы данных, авторизацию и служебное поведение запроса.
URL и шаблоны URI
Адреса и помогают выполнять запросы и находить ресурсы без скрытого знания внутренней модели.
Поведение клиентов
Клиенту важны , и устойчивость к новым полям в JSON.
Дизайн URL
Практика
API Gateway
Маршрутизация, граничные политики и обработка запросов
Для REST-подхода URL должен называть ресурс, который вернётся в ответе, а не алгоритм его получения.
Хорошо
- Существительные в URL
- Множественное число для коллекций
- Свойства в сегментах пути
- Связи между ресурсами в URL
Рискованно
- Глаголы в URL
- Функции вроде convert или translate
- Параметры запроса вместо сегментов пути
- Непредсказуемые структуры адресов
Пример: два вида ссылок на сущность
Поиск по уникальному параметру:
/persons?email=john@example.com
Постоянная ссылка по UUID:
/persons/550e8400-e29b-41d4-a716-446655440000
Если email изменится, постоянная ссылка на ресурс останется прежней.
Дизайн URL для запросов
Авторы предлагают отличать связи между ресурсами от произвольной фильтрации: лучше подходят для устойчивых отношений, а — для поиска и дополнительных условий.
✓ Рекомендуется для связи ресурсов
/persons/{personId}/dogsОтношение владельца и питомцев видно в URL.
✗ Рискованно для базовой связи
/search?type=Dog&owner={personId}Связь спрятана в параметрах поиска.
Главная проверка простая: URL должен помогать клиенту понять, какой ресурс он получит, а не заставлять угадывать внутренний способ вычисления ответа.
Почему ссылки важны
Ссылки превращают JSON из набора полей в навигационную модель: клиент видит не только данные, но и следующие допустимые переходы.
Голые идентификаторы
{
"id": "123",
"name": "Rex",
"ownerId": "456"
}Ссылки на ресурсы
{
"id": "123",
"name": "Rex",
"owner": "/persons/456"
}Такой ответ снижает объём скрытых договорённостей: не нужно заранее знать все шаблоны URI, чтобы перейти к связанному ресурсу.
Содержание книги
Книга проходит путь от базовой модели ресурсов до версионирования, HATEOAS, кэширования и итоговых рекомендаций по Web API.
Главный вывод
Протокол HTTP хорошо задаёт базовую семантику CRUD, но не решает за команду, как выражать запросы к данным, связи между ресурсами и правила навигации. Именно поэтому дизайн URL и представлений остаётся отдельной инженерной работой.
Связанные главы
- Continuous API Management (short summary) - Операционная модель API-продукта: жизненный цикл, управление контрактами и безопасная эволюция интерфейсов.
- API Design Patterns (short summary) - Паттерны контрактного дизайна и правила обратной совместимости для долгоживущих API.
- API для людей: как сделать интерфейс понятным - Клиентский взгляд на API: понятность, предсказуемость и снижение порога входа для разработчиков.
- API Gateway - Практическая реализация маршрутизации, политик на границе системы и контроля трафика для Web API.
- Паттерны межсервисной коммуникации - Как качество API-контрактов влияет на устойчивость и стоимость межсервисных интеграций.
- API Security Patterns - Безопасность Web API: аутентификация, авторизация, модели угроз и применение политик доступа.
- Learning GraphQL (short summary) - Сравнение REST-ориентированного дизайна с GraphQL-подходом и компромиссами клиентского API-слоя.