### restful接口的设计规范
restful设计方法规定了一下几个方面:
- 域名
- 尽量每个域名(二级域名)完成每块功能
- 如果API很简单就放在主域名下
- 版本
- 应该将API的版本号放入URL路径中;示例:
```python
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
http://www.example.com/app/2.0/foo
```
- 另一种方式就是将版本号放在HTTP请求头中,这种方法没有放在url中方便,直观
- 路径
- 资源路径中只能有名词,不能有动词,而且所用的名词往往与数据库的表名相对应
- API中的名词应该使用复数
- Http动词(请求方式)
- 常用的HTTP动词有下面四个(括号里是对应的SQL命令)
- GET(SELECT):从服务器取出资源(一项或多项)
- POST(CREATE):在服务器新建一个资源
- PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
- DELETE(DELETE):从服务器删除资源
- 还有三个不常用的HTTP动词
- PATCH(UPDATE):在服务器更新(更新)资源(客户端提供改变的属性)
- HEAD:获取资源的元数据
- OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的
- 参数
- 根据不同的请求方式,传递参数的格式也不一样;一般来说
- 使用GET方式请求查询数据库数据:
- 如果是查询一条数据则将数据的id以路径拼接参数的方式传递给服务器
- 如果是要查询所有的数据则直接在路径中使用API的复数名词即可,不用跟数据的id;
- 如果要查询表中的多条数据则以查询所有数据的方式,然后将筛选条件一个查询参数的格式传给服务器
- 过滤信息
- 如果返回结果很多需要对返回结果进行过滤的话,过滤参数要以查询参数的方式进行传递(如:对返回结果的数量,指定第几页或指定开始位置等都可以通过查询参数进行传递)
- 状态码
- 200 OK - [GET]:服务器成功返回用户请求的数据
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
- 204 NO CONTENT - [DELETE]:用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的
- 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)
- 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功
- 错误处理
- 如果请求错误,服务器向用户返回的信息一般来说是以error为键名,出错的信息作为键值
- 返回结果
- 针对不同操作,服务器向用户返回的结果应该符合以下规范
- GET /collection:返回资源对象的列表(数组)
- GET /collection/resource:返回单个资源对象
- POST /collection:返回新生成的资源对象
- PUT /collection/resource:返回完整的资源对象
- PATCH /collection/resource:返回完整的资源对象
- DELETE /collection/resource:返回一个空文档 |
|