以 RESTful 方式返回具有多种类型的对象

Question

我目前正在设计一个 API 来处理来自移动客户端的请求。为了在后端和客户端之间实现某种程度的解耦，我想以 RESTful 方式定义 Web 服务。我面临的挑战是一次调用返回多个具有不同类型的对象。

假设我们有以下模型：

• 港口 ...顶级入口
• 船棚 ...分配到特定港口 (0..n)
• 船 ...分配给特定的船棚 (0..n)，或直接分配给港口 (0..n)

据我了解 REST，如果我现在想显示港口中的所有船只和棚屋，我会发送两个请求：

/harbours/{harbour_id}/boats 返回所有船只的列表。棚屋中的船将包含一个链接到它们所在的棚屋的 ID

/harbours/{harbour_id}/sheds返回所有棚子的列表

由于我想在移动场景中使用 Web 服务，因此将这两个调用合二为一是理想的。然后，这可以返回嵌套有棚对象的船列表，或者并列返回两种对象类型：

/harbours/22/boats

[
   {
      "id":1,
      "boatName":"Mary",
      "boatShed":{
         "id":1,
         "shedName":"Dock 1",
         "capacity":55
      }
   },
   {
      "id":2,
      "boatName":"Jane",
      "boatShed":{
         "id":1,
         "shedName":"Dock 1",
         "capacity":55
      }
   }
]

或

/harbours/22/boats

{
   "boats":[
      {
         "id":1,
         "boatName":"Mary",
         "boatShedId":1
      },
      {
         "id":2,
         "boatName":"Jane",
         "boatShedId":1
      }
   ],
   "sheds":[
      {
         "id":1,
         "shedName":"Dock 1",
         "capacity":55
      }
   ]
}

我现在的问题是，这些方式中哪一种更接近 REST 背后的理念，还是根本不是 RESTful？

Answer 1

创建一个包含Boat Shed 和Boat 信息的Harbour 模型。如果我在 Java 中实现服务，那么我会做这样的事情：

class Boat{
...
}

class BoatShed{
...
}

class Harbour{
List<Boat> boats;
List<BoatShed> boatSheds;
...
}

您可以创建一个类似/api/harbours/{harbourId} 的 API。

根据您的问题，您想在harbour 中显示所有船只和棚屋，比如id=1234，您可以提出这样的请求：

GET /api/harbours/1234

这将返回Boats 的列表和Boat Sheds 的列表，如下所示：

{
"boats":[
  {
     "id":1,
     "boatName":"Mary",
     "boatShedId":1
  },
  {
     "id":2,
     "boatName":"Mary2",
     "boatShedId":2
  }
],
"sheds":[
  {
     "id":1,
     "shedName":"Dock 1",
     "capacity":55
  },
  {
     "id":2,
     "shedName":"Dock 2",
     "capacity":50
  }
  ]
}

编辑 由于您想通过发送一个请求并排获得boats 和Sheds，根据REST API 设计原则，api/hourbours/{id} 看起来不错。

在请求boats 时获取所有sheds 并不符合理想的REST API 设计，但如果您想达到相同的效果，您可以执行以下操作。

如果你想要那样，那么 first one /api//harbours/{id}/boats 对我来说看起来不错。

Answer 2

正如@Tarken 提到的/boats 请求不应返回顶层的棚子（因为网址假定您要求收集资源Boat）

如果你有如下定义的关系

Harbour:
    boats: Boat[]
    sheds: Shed[]

Shed:
    boats: Boat[]

Boat:
    harbour: Harbour
    shed: Shed

/harbours/ID 然后返回带有boats 和sheds 关系集的Harbour 表示。

{
  boats: 
  [
    { Boat },
    { Boat },
    ..
  ],
  sheds: 
  [
    { Shed },
    { Shed },
    ..
  ],
  ...
}

这里没有什么是违反 restful 原则的 - url 唯一地标识一个资源，资源表示可以是任何东西，也可以链接到其他资源。