Мне нравится подход, когда все API классифицируются (изолируются) по потребителям:
1. Пользовательские интерфейсы (UI)
- UI
- Admin UI
- Mobile (ios, android)
Эти API предназначены для использования исключительно на UI клиентах продукта.
Из потребностей можно выделить: агрегации данных из разных сервисов, обогащение по справочникам, удобные пагинации, сортировки и умный поиск (например, с учетом синонимов, автодополнения, инвертированной раскладки, нечеткого соответствия или полнотекстовый).
При этом выборки данных обычно небольшие.
Часто чтобы уложиться в НФТ и реализовать хороший поиск вынуждены делать read model.
Под мобилку могут быть переиспользованы API для UI и пересобраны на BFF, а могут быть написаны свои более подходящие.
А в админке могут быть управления ролями, правами, справочниками - и все такие изменения с обязательным аудитом.
2. Для внешних интеграций (Systems)
Чаще всего интеграции оперируют большими выборками без обогащений по справочникам.
Кому необходимо могут справочник скачать к себе и делать обогащения на своей стороне.
Поиск по текстовым полям отсутствует т.к. интеграциям важнее искать по конкретным идентификаторам сущностей.
Если и применяется пагинация, то стараются применять KeySet чтобы не нагружать БД бессмысленными сортировками или поисками, а данные часто просто стримятся в ответ, что еще и экономит память.
Эти API стараются держать максимально стабильными (без breaking changes) со строгим версионированием, как например делает Stripe. А OpenAPI спецификации тщательно описываются, чтобы адекватно работала кодогенерация клиентов.
3. Для внутреннего взаимодействия между сервисами в рамках продукта (Internal)
API которым придаются любые нужные формы для внутренних интеграций или используются даже другие протоколы (gRPC к примеру).
Релизный цикл очень высокий, легко договориться о breaking changes.
Аутентификация через выдачу внутренних JWT токенов (Client Credentials) или mTLS.
Примеры API:
- Передача данных о новом заказе от сервиса оформления заказов к сервису обработки платежей.
- Синхронизация данных между микросервисами в рамках одной платформы.
4. Для поддержки, миграций и прочего (maintenance)
Служебные API для healthchecks, readiness, metrics, отдачи версии приложения.
Служебные API для инженеров поддержки. Что-то пересчитать, подправить, синхронизировать и т.п.
Миграционные API могут быть полезны когда нужно создать схемы БД, мигрировать данные из одной версии в другую, что-то массово обновить, наполнить справочники или прогреть кэши.
Эти API могут быть опасными поэтому должен быть аудит и авторизация пользователей.
В итоге, классификация API по потребителям позволяет четко разделить ответственность, оптимизировать производительность и упростить разработку и поддержку, за счет некоторого дублирования кода.
Каждый потребитель имеет свои особенности, которые необходимо учитывать при проектировании, чтобы обеспечить удобство использования, масштабируемость, безопасность и стабильность системы.
А для того чтобы потребители не путались, все API стоит также группировать по разным OpenAPI спецификациям.
1. Пользовательские интерфейсы (UI)
- UI
- Admin UI
- Mobile (ios, android)
Эти API предназначены для использования исключительно на UI клиентах продукта.
Из потребностей можно выделить: агрегации данных из разных сервисов, обогащение по справочникам, удобные пагинации, сортировки и умный поиск (например, с учетом синонимов, автодополнения, инвертированной раскладки, нечеткого соответствия или полнотекстовый).
При этом выборки данных обычно небольшие.
Часто чтобы уложиться в НФТ и реализовать хороший поиск вынуждены делать read model.
Под мобилку могут быть переиспользованы API для UI и пересобраны на BFF, а могут быть написаны свои более подходящие.
А в админке могут быть управления ролями, правами, справочниками - и все такие изменения с обязательным аудитом.
2. Для внешних интеграций (Systems)
Чаще всего интеграции оперируют большими выборками без обогащений по справочникам.
Кому необходимо могут справочник скачать к себе и делать обогащения на своей стороне.
Поиск по текстовым полям отсутствует т.к. интеграциям важнее искать по конкретным идентификаторам сущностей.
Если и применяется пагинация, то стараются применять KeySet чтобы не нагружать БД бессмысленными сортировками или поисками, а данные часто просто стримятся в ответ, что еще и экономит память.
Эти API стараются держать максимально стабильными (без breaking changes) со строгим версионированием, как например делает Stripe. А OpenAPI спецификации тщательно описываются, чтобы адекватно работала кодогенерация клиентов.
3. Для внутреннего взаимодействия между сервисами в рамках продукта (Internal)
API которым придаются любые нужные формы для внутренних интеграций или используются даже другие протоколы (gRPC к примеру).
Релизный цикл очень высокий, легко договориться о breaking changes.
Аутентификация через выдачу внутренних JWT токенов (Client Credentials) или mTLS.
Примеры API:
- Передача данных о новом заказе от сервиса оформления заказов к сервису обработки платежей.
- Синхронизация данных между микросервисами в рамках одной платформы.
4. Для поддержки, миграций и прочего (maintenance)
Служебные API для healthchecks, readiness, metrics, отдачи версии приложения.
Служебные API для инженеров поддержки. Что-то пересчитать, подправить, синхронизировать и т.п.
Миграционные API могут быть полезны когда нужно создать схемы БД, мигрировать данные из одной версии в другую, что-то массово обновить, наполнить справочники или прогреть кэши.
Эти API могут быть опасными поэтому должен быть аудит и авторизация пользователей.
В итоге, классификация API по потребителям позволяет четко разделить ответственность, оптимизировать производительность и упростить разработку и поддержку, за счет некоторого дублирования кода.
Каждый потребитель имеет свои особенности, которые необходимо учитывать при проектировании, чтобы обеспечить удобство использования, масштабируемость, безопасность и стабильность системы.
А для того чтобы потребители не путались, все API стоит также группировать по разным OpenAPI спецификациям.