描述请求和返回数据的 REST API 响应答案

【问题标题】：REST API response describing request and returned data描述请求和返回数据的 REST API 响应
【发布时间】：2017-12-03 04:28:09
【问题描述】：

在实施之前，我正在考虑生成我正在研究的 REST API 的 JSON 响应的结构。我在这里经历了许多关于 SO 的 Q/A，阅读了许多文章、建议和伪标准。

要求

通知客户端一些有用的元信息 - HTTP 状态码等
分页和过滤信息 - 偏移量、限制和过滤查询（API 客户端知道影响结果的所有参数）。
有关数据收集的信息 - 收集中的总记录数和返回的项目数。然后 API 客户端可以创建分页。
上一页和下一页的链接（只是考虑，不确定这是否可用于 API 客户端，但许多 REST API 链接部分使用 - 例如 PayPal）

回应

这是我返回搜索结果数据结构的初稿：

{
    "meta": {
        "status_code": 200,
        "success": true,
        "server_time": "2017-06-29T15:24:40+0200"
    },
    "request": {
        "offset": 5,
        "limit": 5,
        "query": [
            "foo",
            "bar"
        ]
    },
    "response": {
        "count": 5,
        "total_count": 754,
        "data": [
            {
                "id": "88b60cc6-70bc-4b1a-8f26-c919355d47d3",
                "name": "Name of entity 1"
            },
            {
                "id": "2f4ccda5-11bc-4ef7-b663-30c506f5118c",
                "name": "Name of entity 2"
            },
            {
                "id": "1333f2fe-a958-474e-9a82-8b343fda3aff",
                "name": "Name of entity 3"
            },
            {
                "id": "f5187143-f3b8-412b-a416-1e3a5830baee",
                "name": "Name of entity 4"
            },
            {
                "id": "2dd17750-bbdf-460a-abec-1f74e1170726",
                "name": "Name of entity 5"
            }
        ]
    },
    "links": {
        "previous": {
            "href": "http:\/\/api.example.com\/envelopes?offset=0&limit=5",
            "rel": "previous",
            "method": "GET"
        },
        "self": {
            "href": "http:\/\/api.example.com\/envelopes?offset=5&limit=5",
            "rel": "self",
            "method": "GET"
        },
        "next": {
            "href": "http:\/\/api.example.com\/envelopes?offset=10&limit=5",
            "rel": "next",
            "method": "GET"
        }
    }
}

我想避免“意见问题”来讨论最合适的 JSON 结构。我看到很多关于信封的意见作为回应，一些服务/标准推荐，一些不推荐。

问题：

以这种结构返回结果是个好主意吗？
您是否发现此结构存在一些问题？怎样做更好？
您是否看到 API 客户端所需的一些缺失值？一些不必要的值？
需要返回self的URL吗？

【问题讨论】：

为什么将请求成功作为元信息返回？无论如何，这应该在 HTTP 响应标头中可用。我不确定请求参数是否对返回有用，因为客户希望知道她无论如何都要求。 response 元素也是多余的：很明显，返回的数据是一个响应，因此用不需要的数据使响应膨胀。链接部分上的关系名称已被 JSON 元素覆盖。因此，额外的rel 字段也是多余的。如果您应用所有建议，您的方法类似于 JSON-HAL

标签： json rest api data-structures

【解决方案1】：

意见问题很难，但我会尝试。

首先，您的问题不应针对社区，而应针对客户本身。没有什么比这样的反馈更能清除关于缺失/必要值的假设了。

结构本身已经足够好，至少作为草稿。在设计响应时，您需要记住您基本上将自己锁定，因为客户不喜欢 API 的根本变化。只有很多增量“请在此处再添加一个字段”。您在考虑元字段、分页和分离实际响应方面做得很好，但不要认为您可以预测一切。你不会的。也许寻找像HAL 或JSON Collection 这样的东西。至少作为一种灵感。

API 的最终设计是渐进式的，主要是客户端驱动的过程。所以和你的客户谈谈吧。

【讨论】：