Restful API 设计示例

Restful API 设计示例

一 ，HTTP状态码

✔️正例：

200: 返回成功

说明：200表示成功，4xx表示客户端异常，5xx表示服务端异常，参见HTTP 的返回码含义

❌反例：

除了200就是500

说明：如果不细化状态码，前端很难充分的显示错误信息，比如警告信息和错误信息显示样式不一样

二 ， 返回数据格式

✔️正例：

{

"data": {}, 

"message": "Success!", 

"status": 0, 

"requestId": 1609139633881
}
1
2
3
4
5
6
7
8
9
10

说明：data 主要负责存放数据，message 主要存放应用的请求日志， status 负责存储应用状态， requestId 负责存储本次请求的唯一识别码，方便排查错误

❌反例：

{

"data": {"userid": 123}

}
1
2
3
4
5

说明：只有数据，出了异常前端很难识别

三， 请求方法

✔️正例：

GET： 获取数据

POST： 创建数据

PUT： 更新数据

DELETE： 删除数据

说明：很容易和资源的操作的增删改查对应起来，一个路由多次使用，减少路由的数量

❌反例：

获取数据，使用GET

所有的接口都是POST

说明：获取数据必须是幂等（不改变结果）， 可以直接在浏览器调试，更方便

四， 请求URL格式

✔️正例：

/event/type/element

说明：很容易看出来是递进关系，需要操作的是事件类型要素，尽量不要使用复数

❌反例：

/event_type_element

说明：没有递进关系

❌反例：

/data/import

说明：最好不要出现动词，否则破坏超文本协议（HTTP）对资源的抽象的概念，这种情况可以写成/importor/extract_data 表示导入抽取数据