restful 接口设计规范
1.URL中不能有动词,只能是名词
说明: restful风格将应该遵循统一接口原则,把URL当成一种资源,通过HTTP方法来理解其含义。 因此URL中不能有动词,而应该通过HTTP方法的GET/POST/PUT/DELETE方法来表示 查询/新增/修改/删除
正例: GET /zoos/animals
**反例:**GET /zoos/getAnimals /zoo/get_animals /zoo/get-animals
2.URL结尾不应该包含斜杠“/”
说明:这是作为URL路径中处理中最重要的规则之一,正斜杠(/)不会增加语义值,且可能导致混淆。REST API不允许一个尾部的斜杠,不应该将它们包含在提供给客户端的链接的结尾处。
正例: GET /zoos/animals
反例: GET /zoos/animals/
3.多个单词应该使用"_"分开,不能使用驼峰命名,规避大小写敏感的问题
4.URL路径中首选小写字母
5.RESTful API对资源的操作
- GET: 获取资源
- POST: 新建资源
- PUT:在服务器更新资源(向客户端提供改变后的所有资源)
- PATCH: 一般不用,就使用PUT
- DELETE:删除资源
安全: 请求是否会给服务器带来副作用,即该操作用于获取信息而非修改信息。如get是安全的,而post不安全
幂等: 不管进行多少次操作,结果都一样。
GET和HEAD既安全又幂等,POST既不安全又不幂等,PUT和DELETE不安全但是幂等
6.使用(?)进行资源过滤
说明:获取单个资源时,直接/后面跟资源ID,在获取需要过滤的资源时,使用?来进行过滤
正例: GET /zoos/animals/1 /zoos/animals?type=bird&id=1&color=green
反例: GET /zoos/animals?id=1
7.版本号
说明:可以在headers中自定义版本号,更一般的做法是在URL中说明版本号,github和oschina采用此做法
正例:/v1/users/1
反例:/users/1?version=v1 /users?version=v1&id=1
8.返回状态码推荐标准HTTP状态码
说明:任何接口都应该返回标准HTTP标准码,且服务间的调用 服务提供方一定要提供接口返回信息,且业务校验抛出的异常HTTP状态码应该返回200,而在返回体中说明错误码,以及错误提示信息,不能接口返回void,靠HTTP状态码判断成功失败。
- 1xx:相关信息
- 2xx:操作成功。
- 3xX:重定向
- 4xx:客户端错误
- 5xx:服务器错误
9.对于状态的修改,将状态抽象为一个资源。
说明:我们的业务经常对某一个资源进行状态的变更,在restful风格中,把状态也抽象为名词,用HTTP方法来表示要进行的操作。
正例:PUT /user/state 请求体参数是 state=open
反例:PUT /user/updateState /user/update_state /user/update-state
10.对于查询参数很长的场景必须使用POST方法
说明: 在开发RPC接口的过程中,经常会遇到对外提供批量查询接口的场景,这个时候有可能查询条件很长从而触发http协议url长度的限制,因此在这种场景下必须提供POST方法来提供查询