На что опереться при проектировании API (паттерны, концепции)?

Question

[Александр]

Вот пришел ко мне товарищ и говорит, мол а почему я не могу в API сделать метод DELETE и в него передавать и тип объекта, и его id. Ну я вроде и рассказал, что это противоречит тому же SOLID, что надо делать для каждого типа объекта свой метод и т.д.
Но хочется дать почитать какую-то статью по этому поводу, а выдача забита или неинформативными статьями "как сделать REST API" или прям по-взрослому книжками типа "Проектирование веб-API".
Есть где кратко изложенная теория по этому поводу?

Answer 1

[Сергей Соловьев]

Ну я вроде и рассказал, что это противоречит тому же SOLID

Проектировать API надо по требованиям предметной области.

SOLID, REST и т.д. - это конечно же хорошо, но когда из-за них архитектура становится трудной к пониманию - тупое следование им только усугубит ситуацию.

а почему я не могу в API сделать метод DELETE и в него передавать и тип объекта, и его id

Почему нет? Если объекты создаются динамически, а не предопределены, то передавать их тип - хорошая идея.
Все зависит от проблемы.

Есть где кратко изложенная теория по этому поводу?

Вряд-ли. Все зависит от проблемы/предметной области.
Могу посоветовать алгоритм:
1. Выявить функциональные требования к системе
2. Представить их в виде условных функций
3. Переписать их в виде вызовов API (за основу можно взять готовые паттерны проектирования: REST, SOAP и т.д.)

Посмотрите на API VK или Telegram. Это не REST, но тоже удобно

Comments

[Александр]

Ну там есть, как минимум, иерархические связи у объектов. Типа есть офис, у него клиент, у него задачи, у них подзадачи. Все это с разными статусами. Как по мне, так винегрет получится все это проверять. Т.е. можно сделать, конечно, фасад, там все принимать и потом разруливать. Но мне кажется, что это порождает излишнюю сложность, хотя и экономит код.

[Сергей Соловьев]

Александр, если уж так глубоко, то можно сделать зоопарк микросервисов, который будет предоставлять обширный интерфейс. А внешним пользователям предоставлять интерфейс через gateway, BFF и т.д.

[Сергей Соловьев]

Александр, а вообще, надо ориентироваться на удобство пользователя. если из-за внутренней архитектуры более удобный внешний интерфейс сделать трудно, то значит у внутренней архитектуры проекта проблемы и надо переписывать/рефакторить

Answer 2

[Василий Банников]

Вот пришел ко мне товарищ и говорит, мол а почему я не могу в API сделать метод DELETE и в него передавать и тип объекта, и его id.

Может, да только это не по ресту будет.
А если по ресту - тип и id и так передаются в URL.
Но рест - это не стандарт и не Верховная истина,
Если мешает иерархия, то никто не запрещает делать один ресурс доступным по нескольким разным путям.
и при необходимости его можно нарушать - так появился jsonrpc например

Answer 3

[historydev]

Вопрос безумно банальный и противоречит как минимум DRY и Single responsibility, скорее всего ещё куче других слов из интернетов.

Пусть для начала разберётся что такое api и ООП, а уже потом "проектирует" его.

https://aws.amazon.com/ru/what-is/api/

Comments

[Василий Банников]

и противоречит как минимум DRY и Single responsibility

В каком месте?

[historydev]

Василий Банников,

Он хочет использовать один end-поинт для кучи задач, говорит само за себя.

Там и скорее всего копи-пастный монолит.

[Василий Банников]

historydev, ну лично я из вопроса не понял, какой будет результат - не достаточно данных чтобы утверждать

А как тут dry нарушается?

[historydev]

Василий Банников,

Там и скорее всего копи-пастный монолит.

[Василий Банников]

historydev, ну "скорее всего" - это не аргумент) Тем более что монолит - не порок.

[historydev]

Василий Банников,

А что я ещё могу сказать из трёх невнятных слов в вопросе? Там больше о том, как ему поведать это "товарищу", а не о том, что там вообще происходит)