我的 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,
        ...
    }
}

我见过两种方式都这样做。将数据包装在父级中是最佳实践吗？如果是这样，为什么？父级中还有什么？

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

Answer 1

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

\n\n

\n\n

\xe2\x80\x9c我不喜欢封装数据。它只是引入了另一个键来导航可能密集的数据树。元信息应位于标题中。\xe2\x80\x9d

\n\n

\xe2\x80\x9c 嵌套数据的一个参数是提供两个不同的根键来指示响应的成功， data 和 error 。不过，在发生错误时，我将这种区别委托给 HTTP 状态代码。\xe2\x80\x9d

\n\n

\xe2\x80\x9c 最初，我认为封装数据是不必要的，HTTP 本身提供了足够的 \xe2\x80\x9cenvelope\xe2\x80\x9d 来传递响应。然而\xe2\x80\xa6 我现在建议封装。\xe2\x80\x9d

\n\n

\n\n

\xe2\x80\x9cHTTP 是你的信封\xe2\x80\xa6 话虽如此，在响应上有一个描述性主体并没有什么问题\xe2\x80\x9d

\n\n

\n\n

\xe2\x80\x9cDon\xe2\x80\x99t 默认使用信封，但在需要时可以使用\xe2\x80\x9d

\n\n

\xe2\x80\x9c我们可以通过默认情况下保持无信封并仅在特殊情况下才进行信封来证明 API 的未来。\xe2\x80\x9d

\n\n

\xe2\x80\x9c有 2 种情况确实需要信封 - 如果 API 需要支持通过 JSONP 的跨域请求，或者客户端无法使用 HTTP 标头。\xe2\x80\x9d

\n\n

\xe2\x80\x9c 喜欢信封的 API 通常在信封本身中包含分页数据。我不责怪他们 - 直到最近，还没有更好的选择。今天包含分页详细信息的正确方法是使用 RFC 5988 引入的链接标头。\xe2\x80\x9d

\n