Entity-based VS Consumer-oriented API

Из всех способов организации апи, можно выделить два основных: ориентированных на клиентов или ориентированных на внутренние сущности и структуру данных системы.

Последний способ это когда API напрямую отражает внутреннюю модель: сущности, связи и CRUD-операции. По началу он кажется удобнее, потому что подходит сразу для всех, не надо дублировать эндпоинты под разные сценарии и хорошо ложится на задачи решаемые сервисом.

Потом внезапно оказывается, что для фронтендовых страниц нужен один набор данных, для мобилки другой. И если оставаться в рамках единого апи, то приходится выкручиваться делая серии запросов и объединяя данные на клиенте. А еще разные уровни доступа, разные способы аутентификации и так далее. Каждый раз когда меняется любой эндпоинт, надо помнить про всех возможных клиентов и случайно не сломать логику, которая затрагивает всех, например изменив выборки в коллекциях. В этом случае интерфейс не ломается, но данные будут другими.

Немало людей сталкиваясь с этими проблемами, начинают винить REST, что это его ограничения и его природа. Но нет, просто невозможно спроектировать entity-based API как внешний контракт, хорошо подходящее сразу и идеально для всех. Поэтому есть другой способ, это api ориентированное на клиента. Когда API проектируется от конкретных сценариев использования (use cases), а не от структуры данных. В этом случае у нас нет просто общих эндпоинтов, все эндпоинты разделены по своим неймспейсам, одни для админки, другие для мобилки, третьи для клиентской части сайта, ну и классическое апи для внешних клиентов (не браузера и не мобилки).

При таком подходе обязательным становится внедрение сервисного слоя (use cases), чтобы обработчики эндпоинтов делегировали работу дальше, а не пытались ее выполнить сами, например, взаимодействуя с базой данных.

Entity-based API хорошо подходит как внутренний слой (Service API), но в качестве внешнего API почти всегда приводит к усложнению клиентов и росту связности. Consumer-oriented API, наоборот, берет на себя сложность внутри системы и упрощает клиентов, даже если это приводит к дублированию и большему количеству эндпоинтов.

Telegram | YouTube | Сообщество