Оригинальный источник: Compose your API surface with Data API builder custom paths
Новая поддержка составных REST-путей в Data API Builder может выглядеть как небольшое улучшение конфигурации, но на деле она решает давнее напряжение в дизайне API: утечку топологии базы данных в дизайн публичных эндпоинтов.
Маршруты по умолчанию, основанные на сущностях, отлично подходят для быстрого старта. Они часто неверны для долгосрочных продуктовых API. Реальным системам нужны структуры маршрутов, соответствующие бизнес-концепциям, границам владения и ментальным моделям потребителей.
Именно поэтому это изменение в DAB важно. Вы можете сохранить удобство генерируемого API, представляя при этом более чистую, ориентированную на домен поверхность.
Моё оценочное мнение простое: если структура пути вашего API отражает сырые имена таблиц в продакшне, вы обычно оптимизируете под удобство бэкенда за счёт ясности для клиента.
С кастомными путями команды могут моделировать более качественные границы, такие как продажи, биллинг, поддержка или партнёрские поверхности. Это не заменяет должное управление API (governance), но даёт пользователям DAB практический способ согласовать дизайн маршрутов с языком продукта.
Практические рекомендации для команд, внедряющих эту функцию:
Определите политику именования прежде, чем добавлять пути специально под задачу. Несогласованные подсегменты со временем превращаются в долгосрочный беспорядок.
Отображайте эндпоинты на ограниченные контексты (bounded contexts), а не на организационные схемы. Команды меняются; семантика домена должна быть стабильной.
Относитесь к структуре пути как к части вашей стратегии версионирования и явно документируйте ломающие изменения.
Проверяйте поведение авторизации вдоль кастомных структур маршрутов, чтобы ясность маршрута сочеталась с ясностью безопасности.
Что мне в целом нравится в DAB — это модель рычага: вы получаете пагинацию, фильтрацию, проекцию и другую механику эндпоинтов, не пиша повторяющийся код контроллеров. Кастомные пути делают этот рычаг более готовым к продакшну, устраняя одно из главных возражений архитекторов API.
Есть одна оговорка. Более удобная композиция путей может искушать команды раскрывать слишком много и слишком быстро, потому что генерация кажется лёгкой. Ограждения по-прежнему важны: держите раскрытие сущностей осознанным, применяйте политику централизованно и избегайте случайного построения публичных контрактов из внутренних экспериментов со схемой.
Для .NET-организаций под давлением сроков поставки эта функция — раскрытие продуктивности при дисциплинированном использовании. Вы можете двигаться быстрее, чем с вручную написанными слоями API, сохраняя при этом связную и удобную для бизнеса поверхность эндпоинтов.
Итог: кастомные пути DAB — не про украшательство URL. Они про возвращение намерения в дизайн API при сохранении операционной эффективности генерируемых эндпоинтов.
