基本規(guī)范
協(xié)議：https
通信數(shù)據(jù)格式：JSON
命名規(guī)范：
- 接口命名：統(tǒng)一使用
小寫字母加“-”钞楼，如add-service - 接口參數(shù)命名：統(tǒng)一使用
小寫字母 + '_'下劃線分隔，如：user_id
返回格式：{"code" : 200, "message" : "success", "data" : {}}
返回狀態(tài)碼：
- 協(xié)議級(jí)（如：200席噩、301匾浪、302、401、403桌肴、502）
- 系統(tǒng)級(jí)（如：10001、10002）
- 業(yè)務(wù)級(jí)（如：20001琉历、30001坠七、50001）
- 異常級(jí)（如：40001）
標(biāo)準(zhǔn)請(qǐng)求：
- GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）
- POST（CREATE）：在服務(wù)器新建一個(gè)資源
- PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供完整資源數(shù)據(jù)）
- PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供需要修改的資源數(shù)據(jù)）
- DELETE（DELETE）：從服務(wù)器刪除資源
RESTful API 中的 url 是指向資源的水醋，而不是描述行為的，因此設(shè)計(jì) API 時(shí)彪置，應(yīng)使用名詞而非動(dòng)詞來描述語義拄踪。
備注：不強(qiáng)制要求
代碼實(shí)現(xiàn)：
- GET 請(qǐng)求
? 公開的查詢接口（無需鑒權(quán)） - POST 請(qǐng)求
? 增刪改接口
? 私密的查詢接口（需要鑒權(quán)）
備注：通過修改路由規(guī)則實(shí)現(xiàn) Restful 標(biāo)準(zhǔn)規(guī)范
API URL 示例
api/名詞/
api/名詞/動(dòng)詞/
api/名詞/名詞-動(dòng)詞/
/api/book/list
/api/book/get
/api/book/update
API 動(dòng)詞示例
參考阿里開放平臺(tái) api 接口文檔
create // 添加
delete // 刪除
update // 更新
get // 獲取
list // 列表
count // 統(tǒng)計(jì)
batch // 批量
search // 搜索
query // 查詢
apply // 申請(qǐng)
confirm // 確認(rèn)
check // 檢查
verify // 驗(yàn)證
change // 更改
fetch // 拉取
push // 推送
send // 發(fā)送
notify // 通知
sync // 同步
bind // 綁定
unbind // 解綁
open // 開啟
close // 關(guān)閉
cancel // 取消
done // 結(jié)束
upload // 上傳
accept // 同意
reply // 回復(fù)
refresh // 刷新（例如：token）
API 參數(shù)
小寫加下劃線
/api/wordbook/list?page=1&page_size=20
API 返回 Json 串
正確：
{"code" : 200, "message" : "success", "data" : {}}
{
"code":200,
"message":"success",
"data":{
"items":[
{
"id":1,
"name":"xxx"
},
{
"id":2,
"name":"xxx"
}
]
}
}
錯(cuò)誤：
{"code" : 404, "message" : "Page not found", "data" : {}}
{"code" : 500, "message" : "Sth. worng", "data" : {}}
{"status" : 10001, "message" : "Id is empty", "data" : {}}
錯(cuò)誤碼：
40x：HTTP 請(qǐng)求錯(cuò)誤
50x：服務(wù)器錯(cuò)誤
1000x：系統(tǒng)錯(cuò)誤
4000x：異常錯(cuò)誤
(2|3|[5-9])000x：業(yè)務(wù)錯(cuò)誤
HTTP 狀態(tài)碼：
200 SUCCESS - GET 獲取資源
201 CREATED - POST 創(chuàng)建數(shù)據(jù)成功時(shí)
204 No Content - 對(duì)不會(huì)返回響應(yīng)體的成功請(qǐng)求進(jìn)行響應(yīng)（比如DELETE請(qǐng)求）
301 Moved Permanently - 請(qǐng)求的資源已永久移動(dòng)到新位置
302 Move temporarily - 臨時(shí)重定向
304 Not Modified - 文檔的內(nèi)容并未改變，禁止包含消息體
400 Bad Request - 請(qǐng)求異常拳魁，比如請(qǐng)求中的 body 無法解析
401 Unauthorized - 沒有進(jìn)行認(rèn)證或者認(rèn)證非法
403 Forbidden - 當(dāng)認(rèn)證成功惶桐，但是認(rèn)證過的用戶沒有訪問資源的權(quán)限
404 Not Found - 當(dāng)一個(gè)不存在的資源被請(qǐng)求
405 Method Not Allowed - 所請(qǐng)求的HTTP方法不允許當(dāng)前認(rèn)證用戶訪問
410 Gone - 表示當(dāng)前請(qǐng)求的資源不再可用，當(dāng)調(diào)用老版本API的時(shí)候很有用
415 Unsupported Media Type - 如果請(qǐng)求中的內(nèi)容類型是錯(cuò)誤的
422 Unprocessable Entity - 用來表示校驗(yàn)錯(cuò)誤
429 Too Many Requests - 由于請(qǐng)求頻次達(dá)到上限而被拒絕訪問
500 Internal Server Error - 服務(wù)器遇到了一個(gè)未曾預(yù)料的狀況
502 Bad Gateway - 網(wǎng)關(guān)或者代理出錯(cuò)
503 Service Unavailable - 服務(wù)器臨時(shí)維護(hù)或者過載潘懊，服務(wù)器當(dāng)前無法處理請(qǐng)求
504 Gateway Timeout - 請(qǐng)求超時(shí)
