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

Question

[Alex]

Вот пришел ко мне товарищ и говорит, мол а почему я не могу в 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

[Alex]

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

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

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

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

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

Answer 2

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

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

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