При создании API я должен придерживаться небольших функций и большого количества вызовов или нескольких вызовов и больших функций?

У меня есть платформа рельсов, которую я поддерживаю. На нем много разных веб-приложений. Однако теперь клиент запрашивает API, чтобы они могли держать пользователей на своем сайте, но воспользоваться некоторыми автоматизированными задачами, которые у нас есть.

Платформа используется для создания страховых приложений и позволяет осуществлять их покупки онлайн, а также предоставляет способы загрузки документации, связанной с вашей политикой.

Итак, мой вопрос при создании API заключается в следующем:

Когда я должен сделать много вещей, как validate, создать user, user profileи policy, в значительной степени , в то же время. Должен ли я сделать 4 отдельных вызова API и заставить клиента построить 4 вызова на их стороне. ИЛИ Должен ли я иметь один вызов, который исключает множество параметров, который проверяет клиента и создает все эти три вещи одновременно, упрощая вещи для клиента?

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

Будучи на стороне клиента с помощью многих API, я решил сделать его максимально простым для клиента и сделать так, чтобы он сделал всего один вызов. Тем не менее, это приводит к довольно большим functionsв API, который я тоже не фанат.

Как вы предлагаете мне заняться этим?

Как примечание, я не очень уверен в способности клиентов реализовать сложный API на их стороне.

Как насчет обоих? Иметь « низкоуровневый » (так сказать) API, который предоставляет функции системы, и иметь еще один «уровень», который предоставляет сервисы, которые клиент может захотеть сделать. Этот уровень будет использовать необходимые API низкого уровня, но они все еще доступны, если клиент хочет их.

ОБНОВЛЕНИЕ: также включить некоторые из замечательных моментов и комментариев, сделанных другими.

1. Подумайте, нужно ли клиенту когда-либо вызывать один из меньших методов API, например: выполнимо ли вызывать createUserProfile, не вызывая также createUser? Если нет, то не подвергайте этот метод. Спасибо NoobsArePeople2

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

Я думаю, что вы смотрите на это неправильно. Не беспокойся о больших | небольшие звонки или много | несколько звонков.

Подумайте о бизнес-объектах и ​​действиях, которые можно выполнить с помощью | для | против этих объектов.

У тебя есть:

• пользователей
• полисы
• Тарифы
• ...

Поэтому вы должны создавать вызовы API вокруг этих объектов.

• User.Create
• User.UpdatePassword
• Policy.Validate
• ...

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

Проблема с большими вызовами типа «все в одном» заключается в риске побочных эффектов. Если Policy.Create также порождает пользователя и запускает какое-то другое действие, то это нарушит ожидания программистов. Аналогично, множество небольших вызовов вынуждают программиста не забывать вызывать A, а затем B, а затем C, чтобы выполнить «одну» бизнес-операцию.

И как вы будете называть звонки, будет зависеть от того, что Rails и ваши поддерживающие веб-сервисы будут поддерживать.

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

Я думаю, что ваше интуитивное чувство правильно - сделать API простым для потребителей. В некоторой степени, это философия, лежащая в основе потребительских контрактов .

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

Лично мне нравятся API, которые:

1. оптимизированы таким образом, что общие случаи использования могут быть легко выполнены
2. вызовы, связанные с операциями CRUD , ориентированы на пакетную обработку или имеют пакетные версии
3. позволяет размышлять (чтобы люди, пишущие плагины или привязки для других компьютерных языков, могли автоматизировать процесс)