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

Question

在实现之前，我正在考虑生成REST API的JSON响应的结构。我在SO上浏览了许多问答，阅读了许多文章、推荐和伪标准。

要求

1. 通知客户一些有用的元信息-HTTP状态代码等。
2. 分页和过滤信息-偏移，限制和过滤查询（API客户端知道影响结果的所有参数）。
3. 关于数据采集的信息-集合中的总记录计数和返回项的数量。API客户端然后能够创建分页。
4. 上一页和下一页的链接（只是考虑，不确定这是否适用于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结构。我在回复中看到了很多关于信封的意见，有些是它推荐的服务/标准，有些不是。

问题：

1. 在这个结构中返回结果好吗

Answer 1

意见问题很难回答，但我会努力的。

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

结构本身已经足够好了，至少是草图。在设计响应时，您需要记住，您基本上是在锁定自己，因为客户不喜欢API中的根本性更改。只有很多增量“请在此处再添加一个字段”。你在思考元字段、分页和分离实际响应方面做得很好，但不要认为你能预测一切。你不会的。也许可以找一些类似HAL或JSON集合的东西。至少是一个灵感。

最终，API的设计是渐进式的，主要是客户机驱动的过程。跟你的客户谈谈。