API分页标准

Posted 2023-02-19

【中文标题】API分页标准

【英文标题】：API Pagination Standards

【发布时间】：2014-08-16 17:38:48

【问题描述】：

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

链接头

链接：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"

---

在 JSON 响应中

链接：API pagination best practices

例子：

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

问题：

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

【问题讨论】：

您是为自己还是为其他人构建 API？如果是你自己，那么标准都取决于你。

将成为可公开访问的 API mtgapi.com

这不能回答问题。它是您的 API 还是您为客户构建它？如果你发明了它并且人们可以访问它，他们就任你摆布。您可以随心所欲地调用“页面”，并强迫他们进入他们会鄙视您的疯狂架构。但如果是针对客户，他们可能希望首先遵守，如果您有疑问，应该询问。或者，您可以假设全世界都期望 page=1&per_page=30 是一个非常合适的结构，不会造成混淆。添加自己的方法是完全可以的。方法=since&timestamp=xxx&per_page=30&page=2

所以你的回答是“没有标准，我可以做任何我想做的事”？感谢您的输入。在我继续开发之前，我会推迟一些回复。

【参考方案1】：

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

如果您从来没有嵌套对象需要自己的链接，那么使用 Link 标头（稍微）更可取，因为它更正确。嵌套对象的问题是你不能嵌套链接头。

考虑以下集合实体：

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

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

【讨论】：

从我得到的所有反馈中最终这样做了：api.mtgapi.com/v2/cards