调用带有扁平化或不扁平化主体的 HTTP POST API？ [关闭]

Question

我正在开发一个可以返回用户列表的 API：

"users": [
  {
    "userId": 1,
    "name": "John Smith"
    "address": {
      "countryCode": "gb",
      "street": "Orford Street 20",
      "locality": "London"
    }
    "skills": [
      { "skillId": 1, "name": "design" },
      { "skillId": 2, "name": "logotype" }
    ]
  }
]

考虑我需要创建一个具有地址和技能的用户。

哪种正文格式更常用？某种扁平化的东西：

"users": [
  {
    "name": "John Smith"
    "addressCountryCode": "gb",
    "addressStreet": "Orford Street 20",
    "addressLocality": "London"
    "skills": [ "design", "logotype" ]
  }
]

也许尊重与 GET 响应相同的格式：

"users": [
  {
    "name": "John Smith"
    "address": {
      "countryCode": "gb",
      "street": "Orford Street 20",
      "locality": "London"
    }
    "skills": [
      { "name": "design" },
      { "name": "logotype" }
    ]
  }
]

或者可以分步创建用户：

1. 创建用户；
2. 为用户添加地址；
3. 为用户添加技能。

我相信，即使 API 具有 steps 端点，接受包含所有数据的 User 也会阻止多个 Post 查询创建单个用户。

哪种方法更常用？

或者甚至可以使用另一个？

Answer 1

如果您想遵循 Rest 设计，最好为每个操作都有一个端点，所以第 3 种方法是您应该使用的方法。 这种方式有一些优点：

1. 假设您有一个现有用户，并且您想为他分配一个地址。 如果您遵循第一种或第二种方法，现在您需要创建另一个端点，该端点获取 UserId 和 Address，以将其添加到用户。

   但是，如果您遵循第三种方法，那么已经有一个端点可以执行此操作，您可以在这种情况下重复使用它。

2. 在第一种方法中，并不清楚单个动作方法的作用。有一个巨大的方法可以创建一个用户，创建一个地址并将其分配给用户，创建一些技能并将它们分配给用户......

   在第三种方法中，很清楚端点的作用。一个端点创建用户，一个为其创建地址，一个为其创建技能，依此类推。 更改其中一个方法体的原因只有一个。

   您在这里遵守了单一职责原则。

第三种方法可能出现的一个问题是，通过这种方式，我们将有更多的 API 调用来创建用户并为其分配地址。至少会有 2 个 API 调用！

答案是您可以使用 Batch 通过一个 API 调用一次调用多个端点。批处理请求有一些很好的实现，例如OData Batch，您可以使用它们。