RESTful接口设计原则/最佳实践(学习笔记)

时间:2022-04-07 10:48:33

RESTful接口设计原则/最佳实践(学习笔记)

原文地址:http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

1、RESTful接口建议统一使用复数,而不是单数
2、不建议使用HATEOAS
3、在大多数的教案中,都推荐使用Accept Header来指明是xml还是son,而作者建议直接在url中增加.json或者.xml
4、使用snake_case命名风格来给RESTful URL命名,而不是camelCase风格
5、为了保证接口的可读性和友好性,不建议自己将json中多余的空白去除,而是提供格式化良好的信息以满足用户调试的需求,启用gzip同样能够减少到因为空白等问题而引起的数据大小问题。
6、当一个Resource被查询的时候,可能有一些相关的资源需要被关联出来,则可以在参数中携带embed (或者expand),然后可以把相关的资源展开(比如原来描述一个id,现在把id对应的具体对象也查询出来)。
7、原文中一些其它的观点(非常多),因为比较常见/不太容易简单地表述,所以就没有列出来了,最好阅读原文。

个人理解:(非原文观点)

1、关于embed(或者expand)参数而言,如果是用文档式/KeyValue式的NoSQL数据库,则似乎根本不需要,它们本身就把对象聚合在了一起。
2、关于缓存,如果要在RESTful中用好ETag、Last-Modified,假设RESTful后台是关系型数据库,那么如何标识一个资源的版本/修改时间呢?这个其实是非常难的,因为对于一个存在多表联查的对象而言,你可以保证单个表中的信息未更改,你不能保证关联表中的信息未更改,而且当你再增加fields(参考原文)限定的时候,你说在此范围之外的变化算变化还是不算变化?但是用文档式/KeyValue式的NoSQL数据库的话,感觉在大部分场景上就容易得多,因为通常一个Key对应的结果,是固定的,不存在多表联查的问题,那么版本号这件事就可以是一个特殊值被“设计”在对象中。