java - 将元数据添加到RESTful JSON响应的最佳实践是什么？

背景

我们正在构建一个Restful API，该API应该将数据对象作为JSON返回。在大多数情况下，只返回数据对象就可以了，但在某些情况下，返回f.ex。分页或验证，我们需要在响应中添加一些元数据。

到目前为止我们拥有什么

我们包装了所有json响应，例如以下示例:

{
    "metadata" :{
        "status": 200|500,
        "msg": "Some message here",
        "next": "http://api.domain.com/users/10/20"
        ...
    },
    "data" :{
        "id": 1001,
        "name": "Bob"
    }
}

优点

我们可以将有用的元数据添加到响应

缺点

在大多数情况下，我们不需要元数据字段，它为json格式

增加了复杂性

由于它不再是数据对象，而是更像是封装的响应，因此我们不能在f.ex骨架中立即使用响应，而无需提取数据对象。

问题

将元数据添加到json响应的最佳实践是什么？

更新

我到目前为止从以下答案中得到的是:

删除metadata.status并返回http响应代码
改为使用HTTP协议(protocol)(200，500 ...)

将错误消息添加到http 500回复的正文

对于分页，我自然要有一些有关分页结构的元数据，以及嵌套在该结构中的数据

可以将少量元数据添加到http header (X东西)

最佳答案

您有几种方法可以在RESTful API中传递元数据:

HTTP状态码

header

响应正文

对于metadata.status，请使用Http状态代码，这就是为什么!
如果元数据是指整个响应，则可以将其添加为标题字段。
如果元数据仅涉及响应的一部分，则必须将元数据嵌入为对象的一部分。 请勿将整个响应包装在人工信封中，然后将包装器拆分为数据和元数据。

最后，在您的API 中与您所做的选择保持一致。

一个很好的例子是带有分页的整个集合的GET。 GET/项目
您可以在自定义标题中返回集合大小和当前页面。以及标准链接标题中的分页链接:

Link: <https://api.mydomain.com/v1/items?limit=25&offset=25>; rel=next

这种方法的问题是，当您需要添加引用响应中特定元素的元数据时。在这种情况下，只需将其嵌入对象本身即可。并采用一致的方法...始终将所有元数据添加到响应中。因此，回到GET/items，假设每个项目都创建并更新了元数据:

{
  items:[
    {
      "id":"w67e87898dnkwu4752igd",
      "message" : "some content",
      "_created": "2014-02-14T10:07:39.574Z",
      "_updated": "2014-02-14T10:07:39.574Z"
    },
    ......
    {
      "id":"asjdfiu3748hiuqdh",
      "message" : "some other content",
      "_created": "2014-02-14T10:07:39.574Z",
      "_updated": "2014-02-14T10:07:39.574Z"
    }
  ],
  "_total" :133,
  "_links" :[
     {
        "next" :{
           href : "https://api.mydomain.com/v1/items?limit=25&offset=25"
         }
   ]
}

请注意，收集响应是一种特殊情况。如果将元数据添加到集合中，则该集合不再可以作为数组返回，它必须是其中包含数组的对象。为什么是物体？因为您要添加一些元数据属性。

与各个项目中的元数据进行比较。没有什么可以包装实体了。您只需向资源添加一些属性。

一种约定是区分控件或元数据字段。您可以在这些字段前面加上下划线。