Как правильно организовать адреса-методы REST/HTTP для типового веб-приложения?

Question

[Ярослав]

Допустим, мы пишем веб-приложение для управления компанией. У нас есть список сотрудников отдела staff.json на сервере. Веб приложение может запросить его с бэкенда (GET /staff.json) чтобы отобразить на экране, может сделать какие-то изменения и сохранить (PUT /staff.json). На этом этапе - все правильно? Или правильнее POST? Или вопрос личного вкуса, без четкого стилистического правила?

Хорошо, а теперь усложним. Допустим, мы сделали очень полезный метод raise_salary, чтобы повысить всем зарплату. По какому адресу (стилистический вопрос) он должен работать?
- POST /raise_salary/staff.json ?
- POST /staff.json (а в параметрах - command=raise_salary&percent=20, а для другого метода будет другой command) ?
- POST /raise_salary (а в параметрах - file=staff.json&percent=20) ?
- еще как-то? я легко могу еще несколько способов придумать, все будет работать, но что будет более restful?

Если второй вариант (то есть, по имени модифицируемого документа), то как вызывать методы, которые могут обновлять несколько ресурсов на сервере (повысить зарплату трем отделам; повысить зарплату и в бухгалтерии зарезервировать деньги на это)?

Так же, для методов "добавить сотрудника"/"удалить сотрудника"/"обновить сотрудника" как это в идеале должно выглядеть по адресам и методам?

И где основная "библия" этого - rfc2616 (HTTP/1.1) или это слишком низкоуровневое, и есть что-то еще?

Answer 1

[Петр]

GET /staff - список сотрудников, но скорее общий, а не отдела.
Для отдела лучше GET /department/< name or ID >/staff
POST /staff - добавление нового сотрудника
PUT /staff/< id > - изменение всех данных по сотруднику
PATCH /staff/< id > - частичное изменение данных по сотруднику
DELETE /staff/< id > - удаление сотрудника

Для груповых действий над сорудниками можно
POST /staff/actions c телом запроса { "action": "raise_salary", "value": "20%"}
либо POST /staff/< action >, то есть POST /staff/raise_salary с телом {"value": "20%"}