RESTful API 设计风格

1. 什么是RESTful？

restful是一种开发风格而非标准，REST是Representational State Transfer的简称，意为具象状态传输。

每一个url代表一种资源：json格式数据、text文本、图片视频等

客户端与服务器之间，传递这种资源的某种表现形式：

　　1）通过请求头中Content-Type来指明传给服务端的参数类型

　　　　　　"text/plain"、"application/xml"、"text/html"、"application/json"、"image/gif"、"image/jpeg"、"application/x-www-form-urlencoded"

　　2）通过请求头中Accept来指明希望接受服务端的数据类型

　　　　　　Accept: application/json,application/xml;q=0.9,*/ *;q=0.8

 客户端通过HTTP动词，指明对服务器端资源要进行的操作

HTTP METHOD	CRUD
POST	Create
GET	Search
PUT	Update/Replace
PATCH	Partial Update/Modify
DELETE	Delete

 

2. REST常用设计规则

1）协议

一般使用Https协议

 

2）路径命名

尽量用名词复数形式

往往与数据库表明对应

如：/getProjects、/users、/testcaseById?Id=6

 

3）过滤信息

若记录数量很多，服务器不可能将所有数据都返回给前端

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置

?page=2&size=10：指定第几页和每页的数据条数

?sort=name：指定返回结果按照哪个属性排序，以及排序顺序

 

4）域名

尽量使用专用域名：http://api.ergui.site

 

5）版本

在URL中呈现版本号：http://api.ergui.site/app/0.1/

在请求头中呈现版本号：Accept：application/vnd.example+json;version=1.1

 

6）Http请求动词

含义

GET	从服务器获取资源
POST	服务器中新建资源
PUT	在服务器更新资源
DELETE	从服务器删除资源
PATCH	在服务器部分更新资源
HEAD	获取资源的元数据
OPTIONS	获取关于资源的哪些属性是客户端可以改变的信息

例

GET　/projects	获取所有项目信息
POST　/projects	创建一个新项目
GET　/projects/6	获取ID为6的项目信息
PUT　/projects/6	更新ID为6的项目信息（全更新）
PATCH　/projects/6	更新ID为6的项目信息（部分更新）
DELETE　/projects/6	删除ID为６的项目
GET　/projects/6/interfaces	获取ID为6的项目信息中所有的接口信息
GET　/projects/6/interfaces/1	获取ID为6的所有项目信息中ID为1的接口信息

 

7）常见状态码

200　　 ok - [GET]：服务器返回用户请求的数据

201　　 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功

204　　 No Content - [DELETE]：用户删除数据成功

400　　 INVAILD REQUEST - [POST/PUT/PATCH]：用户请求有误（请求参数有误）

401　　 Unauthorized - [*]：表示用户没有权限

403　　 Forbidden - [*]：表示用户得到授权，但是访问被禁止

404　　 Not Found - [*]：用户请求的路径不存在

406 　　用户请求的格式错误

500　　 Internal Server Error - [*]：服务器发生错误

 

8）返回结果

GET　/projects	返回所有项目列表（json数组
POST　/projects	返回新创建的项目信息（单个json
GET　/projects/6	返回单个项目信息 (单个json
PUT　/projects/6	返回更新之后，完整的项目信息（单个json
PATCH　/projects/6	返回更新之后，完整的项目信息（单个json
DELETE　/projects/6	返回空
GET　/projects/6/interfaces/1	返回单个接口信息（单个json

 

9）错误处理

当请求有误时，需将错误信息以json格式返回

{"error":"xxx错误","status_code":401}

 

10）Hypermedia API

超链接API，返回结果中提供链接

 {"link": 
　　　{
   　　　　"rel":   "collection https://www.example.com/zoos",  #表示这个API与当前网址的关系（collection关系，并给出该collection的网址）
   　　　　"href":  "https://api.example.com/zoos",  #API路径
   　　　　"title": "List of zoos",  #API的标题
   　　　　"type":  "application/vnd.yourformat+json"  #返回类型
 　　　}
　}