database - RESTful：何时嵌套 JSON？

Question

假设我正在构建一个 API，其调用返回一组城市，每个城市都与一个州有关系。一个州有很多城市，但一个城市只有一个州。

我可以想象像这样扁平化关系并模糊数据的底层结构，

{ cities : [
    { id: 1,
      name: "Los Angeles",
      state: "CA" }
]}

或者我可以想象构建 JSON 以使城市和州之间的关系显而易见，

{ cities : [
    { id: 1,
      name: "Los Angeles",
      state: { id: 1,
               name: "CA" }
]}

到目前为止，API 的使用者只需要知道状态的名称。他不需要知道其 ID 或获取有关该州的更多信息的方法。以任何一种方式构建 JSON 的优缺点是什么？

score 2 · Accepted Answer

在我看来，你不应该向你的 api 添加无用的信息，但正如@kgb 所说，如果你的 api 容易被扩展，你应该这样设计它。你问到城市和州之间的关系，在我看来，这种关系已经在两者中得到了定义。

所以如果你 100% 确定你的 api 不会扩展状态功能，你应该选择选项 1。如果只有很小的机会，我建议你这样做：

{ cities : [{ 
      id: 1,
      name: "Los Angeles",
      state: { name: "CA" }
  }]
}

score 1 · Accepted Answer

这取决于其他消费者。你有什么？你打算吗？

API 是一种机器接口，消费者的开发人员同样容易使用这两种结构。如果“状态”实体不是复合实体（除了名称没有可用的属性），我最好只显示名称，而不是带有 id 的结构。

如果状态 id 将来可能有用，或者有可能将新属性添加到状态实体，那么您应该从一开始就使用第二种方法。以任何方式更改 API 都会破坏已经编写的软件，因此更改它将使您支持两个不同的版本。方法 1 和 2 之间的更改不向后兼容。

我会选择方法 2。它并不比方法 1 复杂多少，并且有可能扩展状态实体。

还有第三种方法。但它明显更复杂（并且更可扩展）。仅返回状态 id 并创建用于状态实体检索的方法。

2 回答 2