我的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搜索词：“信封”

RESTful API Design Tips from Experience

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

“嵌套数据的一个参数是提供两个不同的根键，以指示响应，数据和错误的成功。但是，在出现错误的情况下，我将此区别委托给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标头。”

“喜欢信封的API通常在信封本身中包含分页数据。我不怪他们-直到最近，还没有很多更好的选择。如今包括分页详细信息的正确方法是使用RFC 5988引入的Link标头。”