Стандартное соглашение REST Api при обновлении дочернего ресурса

Question

У меня есть ситуация: Категория - Основные данные с разными типами. Заказ - имеет ссылку на категорию. Это сопоставление "один-к-одному" из порядка в категорию. В таблице заказов есть столбец внешнего ключа для категории. Теперь API, чтобы получить заказы

/users/orders

Будет ли возвращаемый тип как

{ "name: "abc", "categoryId" : 23 }

будет хорошо, или мы должны вернуть JSON как

{ "name: "abc", "category" : "CAT-A" }

У нас также есть сценарий создания / обновления заказа, в котором клиент знает категорию. Нам нужен API для публикации нового заказа с категорией. Должно ли это быть что-то вроде этого?

1. post /api/orders { "categoryId" : 23, ....}

Или как то так?

2. post /api/orders/category/23/order

Answer 1

Во -первых, используйте идентификаторы (или ссылки!):

{ "name: "abc", "categoryId" : 23 }

или же

{ "name: "abc", "category" : "/api/categories/23" }

не имена (потому что они могут меняться время от времени)

{ "name: "abc", "category" : "CAT-A" }

Для размещения заказов я бы предложил использовать

post /api/orders { "categoryId" : 23, ....}

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

Этот подход

post /api/orders/category/23/order

также будет хорошо. Но клиент должен будет создать URL с информацией, которая уже содержится в теле запроса, поэтому все становится немного сложнее (что, если категории в URL и теле запроса не совпадают? Что делать, если категория в запросе тело отсутствует? Является ли запрос в этом случае действительным?)