json - 我的 API 是否应该将 JSON 数据嵌套在父对象中？

Question

我今天被称为“不专业”，因为我没有将我的 JSON 响应嵌套在父对象中。
GET /users/{id}回应:

{
    "username":"atr217",
    "age":35,
    ...
}

他们期望这样:

{
    "user":{
        "username":"atr217",
        "age":35,
        ...
    }
}

或者也许是这样:

{
    "status":200,
    "message":"OK"
    "data":{
        "username":"atr217",
        "age":35,
        ...
    }
}

我已经看到它是双向的。将数据包装在父级中的最佳做法是什么？如果是这样，为什么？ parent 还有什么？

如果这很重要，我正在使用 SwaggerHub 和 OpenAPI 3。

Answer 1

我找到了正确的 Google 搜索词:“信封”

RESTful API Design Tips from Experience

“我不喜欢封装数据。它只是引入了另一个键来导航潜在的密集数据树。元信息应该放在标题中。”

“嵌套数据的一个论点是提供两个不同的根键来指示响应、数据和错误的成功。但是，我将这种区别委托(delegate)给 HTTP 状态代码，以防出现错误。”

“最初，我认为封装数据不是必需的，HTTP 本身提供了足够的“信封”来传递响应。不过……我现在建议包住。”

When in my REST API should I use an envelope? If I use it in one place, should I always use it?

“HTTP 是你的信封……话虽如此，在响应中包含描述性正文并没有错”

Best Practices for Designing a Pragmatic RESTful API

“默认情况下不要使用信封，但在需要时使其成为可能”

“我们可以通过在默认情况下保持无信封并仅在特殊情况下进行信封来验证 API。”

“有两种情况确实需要信封——如果 API 需要支持 JSONP 上的跨域请求，或者客户端无法使用 HTTP header 。”

“喜欢信封的 API 通常在信封本身中包含分页数据。我不怪他们——直到最近，没有多少更好的选择。今天包含分页细节的正确方法是使用 RFC 5988 引入的 Link header 。”