На тренингах иногда задают вопрос: «как построить дизайн API для доступа к той или иной модели данных, хранящейся в БД?». Стоит ли начинать с этого вопроса или есть получше?
Дизайн API — действительно архитектурное решение и об удобном и практичном API можно говорить долго, существует немало шаблонов и практических подходов.
Только дизайн API строится не от модели данных, хранящихся в базе, а от требований и потребностей использующего его продукта.
А если так, то возникают совсем иные вопросы:
- Кто будет пользоваться API?
- Что они будут делать?
- Как они будут это делать?
- Какие данные необходимы потребителям?
- Все разом или порционно?
- Нужны ли вариации API для различных режимов работы клиентов?
- По какому каналу потребитель будет общаться с API?
- …
Если пойти дальше, то можно начать с вопроса: «Что будет делать клиент?», после чего спросить «Как он будет это делать?». Ответ на второй вопрос ни что иное, как цели существования API.
Пример
Рассмотрим типовую платформу, на которой клиенты могут создавать собственные интернет-магазины.
| Кто будет пользоваться API? | Покупатели |
| Что они будут делать? | Выбирать продукт |
| Как они будут это делать? | 1. Просмотреть каталог продуктов 2. Просмотреть карточку продукта |
Появилось два кандидата на API, рассмотрим «Просмотреть каталог товаров»
На основе режимов работы, получаем два интерфейса (а могли бы сразу вернуть одни ответом полный список продуктов со всеми заполненными атрибутами):
- ProductList, возвращающий заданное число идентификаторов продуктов (список ProductId);
- ProductMetadata, с поддержкой include, запрашивающий данные у соответствующих сервисов только если клиент их запросил (особенно актуально, если хостинг в облаках с оплатой за использование). Например, метод Price сервиса PriceService.
В качестве приятного дополнения можем узнать, что из всех тех данных, что есть у нас в базе, клиентам требуется процентов 20, что сократит затраты и на разработку и на поддержку, причем и со стороны поставщика API и со стороны потребителя (меньше параметров — короче описание, проще разобраться).
О простоте и удобстве
Из вышесказанного второй важный момент: простота и удобство использования API потребителем важнее простоты и удобства реализации поставщиком.
Идеально, если удается сделать простым и удобным и то и другое, но, если нужен компромисс, то потребитель зачастую — важнее, ведь глобально в такой ситуации мы усложняем только поставщика (он остается в зоне нашего контроля и мы можем в будущем упростить дизайн). В противном случае усложняются все потребители, что увеличивает общую сложность кратно их количеству.
Простых и удобных интеграций!
