Створюючи api, я повинен дотримуватися невеликих функцій та багатьох дзвінків, або декількох дзвінків та великих функцій?

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

Платформа використовується для створення страхових заявок та дозволяє придбати їх в Інтернеті, а також надає способи завантаження документації, пов’язаної з вашим полісом.

Тож моє запитання при створенні API таке:

Коли я повинен зробити багато речей, як validate, створити user, user profileі policy, в значній мірі , в той же час. Чи повинен я зробити 4 окремі дзвінки API і змусити клієнта створити 4 дзвінки на їх стороні. АБЛЕ я повинен мати один виклик, який перевищує безліч параметрів, який підтверджує клієнта і створює всі 3 ці речі одночасно, спрощуючи речі для клієнта?

У цьому випадку клієнт отримує всю необхідну інформацію одночасно, тому не подобається, що в їх застосуванні є природний потік, коли він призупиняється, і він може здійснити виклик API на мою платформу.

Якщо раніше я був на стороні клієнта, використовуючи багато API, моя кишка полягає в тому, щоб зробити його максимально простим для клієнта і змусити їх зробити лише один дзвінок. Однак це веде до досить великого functionsв API, який я також не є прихильником.

Як ти пропонуєш вирішити це?

На замітку, я не дуже впевнений у можливості клієнтів впроваджувати складний API на їхньому боці.

Як щодо того, як робити обидва? Майте API " низького рівня " (так би мовити), який відкриває функції системи, і інший "шар", який піддає послугам, які може захотіти зробити клієнт. Цей шар використовує необхідний інтерфейс API низького рівня, але вони все ще піддаються впливу, якщо клієнт цього хоче.

ОНОВЛЕННЯ: Щоб також включити деякі чудові моменти та коментарі, зроблені іншими.

1. Подумайте, чи буде клієнту коли-небудь потрібно зателефонувати одному з менших методів API, наприклад, чи можливо викликати createUserProfile без виклику createUser? Якщо ні, то не піддавайте цього методу. Дякую NoobsArePeople2

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

Я думаю, ви дивитесь на це неправильно. Не турбуйтеся про великі | невеликі дзвінки або багато | кілька дзвінків.

Подумайте про бізнес-об’єкти та дії, які можна виконати з | для | проти цих об'єктів.

У вас є:

• Користувачі
• Політика
• Ціни
• ...

Тож слід створити дзвінки API навколо цих об'єктів.

• User.Create
• User.UpdatePassword
• Політика
• ...

Ідея полягає у створенні атомних або майже атомних операцій на основі ділових об'єктів та їх дії. Це спростить дизайн та кодування - дзвінки, які роблять те, що повинен робити бізнес-об’єкт, що відповідає ментальній моделі або очікуванням програмістів. Коли програмісти або архітектори обговорюють вимоги з бізнес-аналітиками, вони можуть використовувати ту саму термінологію та загальний потік операцій.

Проблема з більш масштабними викликами типу "все в одному" - це ризик виникнення побічних ефектів. Якщо Policy.Create також породжує користувача та запускає якусь іншу дію, то це порушить очікування програмістів. Так само багато невеликих дзвінків змушують програміста пам’ятати про виклик A, а потім B, а потім C, щоб виконати «єдину» ділову операцію.

А те, як ви називатимете дзвінки, базуватиметься на тому, що підтримуватимуть Rails та підтримувані веб-служби.

Для отримання більш чіткої інформації це створить деякі дзвінки, які приймають певну кількість параметрів і можуть мати кілька викликів на зворотному боці, які затемнюються для клієнта. Ви також отримаєте досить швидкі / прості дзвінки, де API трохи більше, ніж обгортка для основної програми.

Я думаю, що ваше відчуття кишечника правильне - зробіть API простим для споживачів. Певною мірою це філософія контрактів, керованих споживачами .

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

Особисто мені подобаються API, які:

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