REST Api. Как выводить вложенные сущности?

Question

[dmitriy]

Привет, по REST API есть пару вопросов. Например есть сущности Заказ, состояние заказа, позиции заказа, клиент заказа
Заказ является агрегатом поэтому от него строим апи,
GET /orders
POST /orders
GET /orders/{id}
PUT /orders/{id}
DELETE GET /orders/{id}

1. Нужно ли выводить полный ответ с связанным сущностями state или достаточно выводить stateId, я предполагаю что стоит выводить id связанных сущностей если они пересекаются с другими агрегатами, например customerId, а сущности получать через ?include=customer

{
"data":{
    "id"=>1,
    "customerId":1,
    "state":{
        "id" => 1,
         "name" => "В работе"
     }
}

2. Стоит ли ответе группировать поля по назначению
например

{
"data":{
    "id"=>1,
    "dates" : {
        "dateCreate" : {
            "date": "2021-07-04 09:05:37.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        },
       "dateUpdate" : {
            "date": "2021-07-04 09:05:37.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        }
    }
}

3. Если в ответе идет группировка полей по тематике, стоит ли аналогичный подход использовать в запросе на создание и обновление?

Answer 1

[nokimaro]

Выводите ровно столько информации, сколько нужно клиенту который с этим api работает и делает отображение данных.
Например надо вывести список заказов и имя клиента, то лучше сразу вернуть customer.name, а не дёргать каждый профиль по customer.id.
Остальное уже дело вкуса, хотите группируйте даты, не хотите не группируйте.

Так же существует GraphQL если нужно больше гибкости.