API分页标准

Question

我一直在开发一个API，需要分页。每个请求中只返回25个元素。我四处寻找标准，似乎看到了两种不同的情况。

1. 链接标题

• 链接：https://www.rfc-editor.org/rfc/rfc5988

示例：

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
  <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

• 链接：API分页最佳实践

示例：

"paging":  {
    "previous":  "http://api.example.com/foo?since=TIMESTAMP"
    "next":  "http://api.example.com/foo?since=TIMESTAMP2"
}

问题：

我应该两者都做吗？话虽如此；“分页”键是正确的键吗？或“链接”或“分页”

Answer 1

我想说，这取决于您返回的数据的结构（将来可能会返回）。

如果没有需要自己链接的嵌套对象，那么使用链接头（稍微）更可取，因为这样更正确。嵌套对象的问题是无法嵌套链接头。

考虑以下集合实体：

{
    "links": {
        "collection": "/cards?offset=0&limit=25"
    },
    "data": [
        {
            "cardName": "Island of Wak-Wak",
            "type": "Land",
            "links": {
                "set": "/cards?set=Arabian Knights"
            }
        },
        {
            "cardName": "Mana Drain",
            "type": "Interrupt",
            "links": {
                "set": "/cards?set=Legends"
            }
        }
    ]
}

没有好的方法可以在标题中包含卡片的链接。