如何设计Restful API的分页？

需要考虑的问题:

• 请求方式
• 回复方式

请求方式

可考虑的传递通道:

• url query, /foo?page=1
• url path, /foo/page/1
• http request json body
• http header

比较:

• page不是resource，所以不应该设计在url path中
• 需要考虑到url复制分享和传统a标签兼容问题的情况，这里还不谈及SEO，所以应该来说url query还是最优选择

数据格式:

• 基于page, [page:4, per_page:50]
• 基于offset, [offset:200, limit: 50]
• 基于cursor, [cursor: timestamp, limit: 50]

page和offset比较简单，但是在large datasets查询时会效率比较低，没有索引，所以才会有cursor方式，但是考虑到github, zoom，同时兼顾client的友好性，采用page-based还是比较折中的选择。

• ?page=2&size=100: 指定第几页，以及每页的记录数
• ?offset=100&limit=10: 指定返回记录的数量
• ?sort=name+,group-: 多属性排序

回复方式

• json
• http header

github比较特殊，采用了将pagination信息已link方式放在了http header中，http body就是比较纯粹的array，所以github翻页也只有上一页，下一页。

一般来说，用json更多一些，回复内容包括:

• total: 总数
• page: 当前页数 (1-based)
• size: 当前每页数量
• items: 具体记录数组