У Майкрософта есть годный гайд по проектированию RESTful веб-API. Там и фундаментальные вещи, и конкретные рекомендации:
— во главу угла ставить ресурс, а не действие. Не делать ручку create-order, вместо неё делать POST-запрос на
orders/<id>. При этом подчёркивается, что внутреннее представление данных не должно просачиваться наружу. То есть за сущностью orders может быть несколько сущностей реальной базы данных— стараться не усложнять ручку больше, чем двойная вложенность
collection/item/collection, например, /customers/<id>/orders. При этом следует найти баланс. С одной стороны, запросы лучше экономить (много запросов = больше нагрузка на сервер и клиент), но при этом на каждый чих слать весь мир в ответе тоже не стоит— приводятся типовые HTTP-методы. Нередко достаточно GET/POST/DELETE, можно добавить PUT и PATCH. К сожалению, часто семантика этих запросов понимается всеми по-разному. В этом гайде представлено довольно практичное описание. По каждому методу даны нюансы как по применению, так и по особенностям реализации в части возврата ошибок и асинхронным операциям. Важно не забывать про идемпотентность (пост о ней) некоторых методов
— не забыта постраничная навигация в запросе, HATEOAS и версионирование API
#systemdesign
