使用 Flatten 或不 flatten body 调用 HTTP POST API？

Question

我正在开发一个 API，它可以 return 用户列表：

"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" }
    ]
  }
]

或者在以下步骤中创建用户：

创建用户；
为用户添加地址；
为用户添加技能。

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

哪种方法更常用？

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

Answer 1

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

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

但是如果您采用了第三种方法，则已经有一个端点可以执行此操作，您可以在这种情况下重复使用它。
在第一种方法中，不清楚单个操作方法的作用。有一个巨大的方法可以创建用户、创建地址并将其分配给用户、创建一些技能并将它们分配给用户以及...

在第三种方法中，很清楚端点的作用。一个端点创建一个用户，一个为它创建一个地址，一个为它创建技能等等。更改这些方法体之一的原因只有一个。

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

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

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

使用 Flatten 或不 flatten body 调用 HTTP POST API？

Call an HTTP POST API with Flatten or not flatten body?

api

api-design

asp.net-core