Question

在实现之前，我正在考虑生成我正在研究的REST API的JSON响应的结构。我在这里经历了很多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的网址？

Answer 1

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

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

结构本身就足够了，至少作为草案。在设计响应时，您需要记住您基本上是在锁定自己，因为客户端不喜欢API的基本更改。只有很多增量“请在此添加一个字段”。你在思考得很好，关于元字段，分页和分离实际反应，但不认为你可以预测一切。你不会。也许找一些像HAL或JSON Collection这样的东西。至少作为灵感。

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

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

1 个答案: