Условное соглашение об именовании конечных точек

Question

Я знаю, что конечные точки REST должны быть существительными вместо глаголов, но иногда возможны небольшие отклонения?

Представьте конечную точку, которая должна опубликовать продукт (сделать его видимым на веб-странице, возможно, добавить что-то в очередь).

Я могу предложить два способа решить эту проблему.

1) PUT api/products/1/publish - Мне нравится, потому что он явный, избегает сложностей на бэкэнд, и он сам документирует.

2) ЗАПЛАТА/PUT/ЗАПЛАТА API/Продукты/1

{ 
    "color": "green", 

    //some properties removed for brevity 

    "ispublished" : true 
} 

Второй подход требует обслуживания серверной, чтобы следить за isPublished поля на пост тела и, когда тот переворачивается к истинному, начало процесс публикации. Это кажется немного более сложным и более важным.

Итак, мой вопрос в том, хорошо ли с точки зрения REST использовать первый подход? Есть ли большие недостатки?

Answer 1

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

REST означает Re презентационное S татэ Т ransfer. Этот архитектурный стиль resource-oriented и независимый от протокола, но часто используется по протоколу HTTP.

При реализации приложений REST по протоколу HTTP ресурс идентифицируется с помощью URI, а операции над таким ресурсом выражаются HTTP methods (любые другие глаголы не нужны). Чтобы изменить состояние ресурса, вы должны отправить серверу представление нового состояния ресурса. Представление может представлять собой JSON, XML или любой другой формат, способный представлять состояние ресурса. Смотрите ниже цитату:

5.2.1.2 Representations

компонента REST выполнять действия на ресурсе, используя представление для захвата текущего или предназначенного состояния этого ресурса и передавая это представление между компонентами. Представление представляет собой последовательность байтов, плюс метаданные представления для описания этих байтов. Другие обычно используемые, но менее точные имена для представления включают в себя: документ, файл и объект сообщения HTTP, экземпляр или вариант.

[...] данное представление может указывать текущее состояние запрашиваемого ресурса, требуемого состояния для запрошенного ресурса, или значение какого-либо другого ресурса [...]

После этого подход, ресурс product может иметь под-ресурс status. В соответствии с вашими потребностями status может иметь разные значения, например draft, published, inactive ...

Затем используйте PUT заменить состояние status подресурсов с JSON, отправленное в запросе полезной нагрузки:

PUT /api/products/1/status HTTP/1.1 
Host: example.org 
Content-Type: application/json 

{ 
    "value" : "published" 
}