想问问各位 restful 风格的 url 设计问题

[lml12377]

遇到这样一个问题，首先是个博客平台，需要获取日志 diary，所以针对日志的 api url 设计为：

/diaries

GET 获取，POST 发表，PUT 修改。

但是用户的博客有日志，其实主域名还有日志的聚合（比如 “发现” 栏目），另外用户是以 domain 短域名进行查询的，比如 /people/lemonlone，这个时候就有个问题，我是应该分开来设计比如：

/people/lemonlone/diaries
/diaries/hot

还是聚合到一起？

/diaries/people/lemonlone
/diaries/hot

另外分页的话，应该是通过 GET 查询参数来进行，还是用斜杠？

/diaries/page/1
/diaries?page=1

求解答！

[terry0314]

/diaries/people/lemonlone
/diaries?page=1
个人更喜欢这两种。

[rwecho]

http://www.ruanyifeng.com/blog/2014/05/restful_api.html
第六:

如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果
下面是一些常见的参数。
```
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
```
参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

[lml12377]

@terry0314 其实我个人也偏向这两种

[lml12377]

@rwecho 明白了，谢谢

[tianshuang]

https://book.douban.com/subject/27054104/

[Mutoo]

先项目，赶紧上 graphql 啊，别再 restful 了！

[geelaw]

page=几 这种设计容易导致错过一些内容。一个简单的想法是传入看到的最后一个对象 id，下次从下一个开始返回。

更好的方法是让客户端不需要知道怎么查看“下一页”，把分页 API 的下一页地址在本次查询返回。

[XiaoFaye]

@Mutoo 在正式项目里乱试新技术是找死。。。

[zonghua]

@XiaoFaye 有人直接拿 RPC （如：Thrift ）在 Web 端使用的吗？ REST 做数据校验和文档太烦人了。

[watsy0007]

restful 是按资源来的。
按照业务需求，设计资源返回数据。
也就是看你接口的业务描述更偏向于哪种。
针对用户的，当然是用户层面的。
针对聚合的，是聚合的资源组织。
如果 2 种业务需求都有，当然可以都要。
最好不要 1 个资源满足不同的业务需求。以后改的时候会死人。
page limit 属于参数 。

[hantsy]

如果你公司不在乎标准，就用好与不好去区别 API 设计。

如果需要严格按规范来，看看相关的规范。

page 可用参数，也可用在 Header 中。

HAL 标准实现了 Richardson Mature Model Level 3，对查询结果格式作了规范。类似的规范草案还有几个，REST 不是规范，但用于交互的数据格式有不少规范。

http://stateless.co/hal_specification.html
https://tools.ietf.org/html/draft-kelly-json-hal-08

用 Spring 的话，简单的分面直接返回 Spring Page 类就行了。严格按 HAL 来的话，之前项目用 Spring HATEOAS 去实现。其它语言一样，可找到很多类似的框架或工具。