RESTful 接口如何设计好？

[Vimax]

新项目打算用 RESTful 风格设计 API 接口。请问如果设计符合 RESTful 风格规范的 API ？

比如分页查询，之前都是将分页信息放在 URL 参数中，现在使用 RESTful 风格，如何将分页信息传递给后端接收。

如果是用 josn 接收，那么每个分页查询的实体对象是否都做扩展，增加分页参数属性？

请问 RESTful 风格接口的最佳实践是什么？

[xuanbg]

spring 可以用实体类接收 url 参数，这是一个小技巧

[abbycin]

最佳实践就是不用 restful

[baiyi]

月经贴

[baiyi]

@baiyi #3 RESTful 的最佳实践我投 Github 一票，包括主楼提到的分页

[Rwing]

很简单，参考国外大厂

[xingheng]

普通的分页请求不存在写操作，RESTful 只是建议用 GET 吧，请求参数就应该放在 url query path 里面。如果是比较复杂的分页，参数比较复杂或者在业务层上将存在写操作的请求才需要调整成 POST 或者其他的吧。

没有必要纠结参数应该用什么方式回传的，应该先定义用什么请求方法体。规范就是干这事儿的，说错了请纠正我。

[ChanKc]

最佳实践是 hateoas
分页的话，使用 HTTP 的 link 头来给客户端返回上一页，下一页，第一页和最后一页的链接。让客户端根据 link 的关系，也就是 rel 属性自己找去

[libook]

我是 REST 原教主义的，REST 本身只是一套风格和思想，可以用于指导设计出适合自己系统的 API 标准。

没有银弹。建议从实际需求出发，而不是照搬任何现有的 REST 案例，当然如果能找到适合自身业务的一站式的解决方案也可以。

所以像分页这种需求，得看有多少种方案可以选，然后分析每一种对你们的实际情况来说是否是最合适的。
REST 本身对于分页并没有具体的设计，将分页参数放在哪里完全看在业务上你把这些参数归为哪一类，是资源的查询条件还是资源本身或是体系之外的无关信息，你可以继续以 Querystring 的方案来实现，也可以通过在 Header 里传 Range/Content-Range 的方式来实现。REST 要求 API 无状态，所以基于 Cookie 、Session 的翻页就不推荐了。

当然，如果确实找到了一套别人的实践经评估非常适合自己项目的需求，也可以作为第一版方案先用上，等日后再根据项目发展逐步改进。

然后 REST 只是众多 API 设计思想中的一种，有其使用的范畴，也有不适用的范畴，建议不要为了上 REST 而强上，如果业务可以拆分模块的话，也可以考虑不同模块使用不同的 API 方案，比如后台接口用 REST，前台接口用 GraphQL 。

[hantsy]

日经

[hantsy]

我谈过好多次了，不想再聊这个话题了，伤神。

最有效的方法，买本权威的看一下，系统的学习一下， 如：rest in practice.

简单的参考资料，RestCookbook http://restcookbook.com/ ，Restful API 好几个网站等。

REST API 设计的质量，可以参考 Richarson Mature Model 。https://martinfowler.com/articles/richardsonMaturityModel.html

REST 设计的典范，Github API，Heroku 的 API 。

Pagiantions 基本所有的教程，深入一点文章都是讲到，Header Links， 或者 Query Params 。

在没被污染前看一下， 马上反 REST 水军，公司胡来 API 有理的 估计冲上来了。

[hantsy]

我看过这本书： https://www.oreilly.com/library/view/restful-java-with/9781449361433/

[Vimax]

@libook 感谢分享和提供的思路。

[Vimax]

@hantsy 谢谢。吸收并采纳。

[Vimax]

@ChanKc 谢谢，很棒很赞。学习采纳。

[EastLord]

自己查查吧，老哥 这个问题真的被问过太多遍了

[thinkmore]

https://juejin.im/post/5d8485e36fb9a06b0936543c 可以看看这个关于 restful 接口的命名

[MrByte]

@Rwing 看了 ins 和 youtube 的接口设计，比如关注和订阅，也是 follow/unfollow 和 subscribe/unsubcribe