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

Question

I am working on an API which can return a list of Users:

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

Consider I need to create a User with address and skills.

Which body format is more commonly used? Something kind of flatten:

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

Maybe respecting the same format as the GET response:

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

Or maybe creating the User in Steps:

1. Create user;
2. Add address to user;
3. Add skills to user.

I believe that, even if the API has the steps endpoints, one that accepts a User with all data would prevent multiple Post queries to create a single user.

Which approach is more commonly used?

Or maybe even use another one?

Answer 1

如果要遵循Rest Design，最好为每个操作都指定一个端点，因此第3种方法是您应该使用的方法。这种方式有一些优点：

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

   但是，如果您采用了第三种方法，则已经有一个端点可以执行此操作，并且可以在这种情况下重复使用该端点。

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

   在第三种方法中，很明显端点可以做什么。一个端点创建一个用户，一个端点为其创建地址，一个端点为其创建技能，依此类推。更改这些方法主体之一只有一个原因。

   您在这里遵守了“单一责任原则”。

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

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