Какие риски возникают при проектировании универсальных endpoint’ов?

Question

Универсальные endpoint’ы выглядят гибко, но быстро теряют прозрачность. Они усложняют валидацию, документацию и тестирование. Поведение становится зависимым от множества флагов и параметров. Ошибки труднее диагностировать, а изменения чаще становятся breaking. В итоге поддержка такого API дороже, чем у специализированных endpoint’ов.

YeaHub · Accepted Answer

ОпределениеУниверсальный endpoint — это API-точка, поведение которой существенно меняется в зависимости от входных параметров или режима работы.Основные рискиСкрытая сложностьБольшое количество условной логики.Трудно понять, какой сценарий будет выполнен.Слабая типизация и валидацияМножество опциональных полей.Ошибки выявляются слишком поздно.Проблемы с документациейКонтракт становится размытым.Клиенты не понимают допустимые комбинации параметров.Рост связанностиИзменение одного сценария затрагивает другие.Повышенный риск регрессий.Сложность тестированияЭкспоненциальный рост кейсов.Сложно покрыть все ветки логики.Когда универсальные endpoint’ы допустимыДля read-only запросов с фильтрацией.Для внутренних API с контролируемыми клиентами.ВыводУниверсальные endpoint’ы редко масштабируются по сложности: чаще всего несколько простых и явных endpoint’ов надёжнее и дешевле в поддержке.