1. URI規(guī)范
- 不用大寫
- 用 "-" 不用 "_"
- 參數(shù)列表要encode
- 資源集合,用復數(shù)形式表示
- 在RESTful架構(gòu)中凿将，每個網(wǎng)址代表一種資源（resource）粱腻，所以網(wǎng)址中不能有動詞自晰，只能有名詞（特殊情況可以使用動詞），而且所用的名詞往往與數(shù)據(jù)庫的表格名對應
- 避免層級過深的URI,在url中表達層級热康，用于 按實體關聯(lián)關系進行對象導航 讯沈，一般根據(jù)id導航。
- 應該將API的版本號放入到URI中,https://api.example.com/v1/zoos
2. Request
HTTP方法
通過標準HTTP方法對資源CRUD：
GET：查詢（從服務器取出資源一項或多項）
GET /zoos
GET /zoos/1
GET/zoos/1/employees
POST：創(chuàng)建單個新資源祝迂。 POST一般向“資源集合”型uri發(fā)起
POST/animals //新增動物
POST/zoos/1/employees //為id為1的動物園雇傭員工
3. 狀態(tài)碼
服務器向用戶返回的狀態(tài)碼和提示信息睦尽，常見的有以下一些（方括號中是該狀態(tài)碼對應的HTTP動詞）。
§200 OK - [GET]：服務器成功返回用戶請求的數(shù)據(jù)型雳，該操作是冪等的（Idempotent）当凡。
§201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。
§202 Accepted - [*]：表示一個請求已經(jīng)進入后臺排隊（異步任務）
§204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功纠俭。
§400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤沿量，服務器沒有進行新建或修改數(shù)據(jù)的操作，該操作是冪等的冤荆。
§401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌朴则、用戶名、密碼錯誤）钓简。
§403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對）乌妒，但是訪問是被禁止的。
§404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄外邓，服務器沒有進行操作撤蚊，該操作是冪等的。
§406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式坐榆，但是只有XML格式）拴魄。
§410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的席镀。
§422 Unprocesable entity - [POST/PUT/PATCH] 當創(chuàng)建一個對象時匹中，發(fā)生一個驗證錯誤。
§500 INTERNAL SERVER ERROR - [*]：服務器發(fā)生錯誤豪诲，用戶將無法判斷發(fā)出的請求是否成功顶捷。
URI失效
隨著系統(tǒng)發(fā)展，總有一些API失效或者遷移屎篱，對失效的API服赎，返回404 not found 或 410 gone；對遷移的API交播，返回 301重定向
在Controller層使用統(tǒng)一的異常攔截器：
設置 HTTP響應狀態(tài)碼：對業(yè)務類異常重虑，用它指定的 HTTPcode；對非業(yè)務類異常秦士，統(tǒng)一500缺厉；Response Body的錯誤碼：異常類名Response Body的錯誤描述：對業(yè)務類異常，用它指定的錯誤文本；對非業(yè)務類異常提针，線上可以統(tǒng)一文案如“服務器端錯誤命爬，請稍后再試”，開發(fā)或測試環(huán)境中用異常的 stacktrace辐脖，服務器端提供該行為的開關饲宛。
常用的http狀態(tài)碼及使用場景：
狀態(tài)碼
使用場景
400 bad request
常用在參數(shù)校驗
401 unauthorized
未經(jīng)驗證的用戶，常見于未登錄嗜价。如果經(jīng)過驗證后依然沒權(quán)限艇抠，應該 403（即 authentication和 authorization的區(qū)別）。
403 forbidden
無權(quán)限
404 not found
資源不存在
500 internal server error
非業(yè)務類異常
503 service unavaliable
由容器拋出炭剪，自己的代碼不要拋這個異常,服務器返回的數(shù)據(jù)格式练链，應該盡量使用JSON，避免使用XML
過濾信息
如果記錄數(shù)量很多奴拦，服務器不可能都將它們返回給用戶媒鼓。API應該提供參數(shù)，過濾返回結(jié)果错妖。
下面是一些常見的參數(shù)绿鸣。
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁暂氯，以及每頁的記錄數(shù)潮模。
?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序痴施。
?producy_type=1：指定篩選條件
API 傳入?yún)?shù)
參入?yún)?shù)分為4種類型：
地址欄參數(shù)
* restful 地址欄參數(shù) /api/v1/product/122 122為產(chǎn)品編號擎厢，獲取產(chǎn)品為122的信息
* get方式的查詢字串 見過濾信息小節(jié)
請求body數(shù)據(jù)
cookie
request header
cookie和header 一般都是用于OAuth認證的2種途徑
返回數(shù)據(jù)
只要api接口成功接到請求，就不能返回200以外的HTTP狀態(tài)辣吃。
為了保障前后端的數(shù)據(jù)交互的順暢动遭，建議規(guī)范數(shù)據(jù)的返回，并采用固定的數(shù)據(jù)格式封裝神得。
接口返回模板：
{
status:0,
data:{}||[],
msg:’’
}
status: 接口的執(zhí)行的狀態(tài)
=0表示成功
<0 表示有異常=""
Data 接口的主數(shù)據(jù)
厘惦，可以根據(jù)實際返回數(shù)組或JSON對象
Msg
當status!=0 都應該有錯誤信息
4. 非Restful Api的需求
由于實際業(yè)務開展過程中，可能會出現(xiàn)各種的api不是簡單的restful 規(guī)范能實現(xiàn)的哩簿，因此宵蕉，需要有一些api突破restful規(guī)范原則。特別是移動互聯(lián)網(wǎng)的api設計节榜，更需要有一些特定的api來優(yōu)化數(shù)據(jù)請求的交互羡玛。
頁面級的api
把當前頁面中需要用到的所有數(shù)據(jù)通過一個接口一次性返回全部數(shù)據(jù)
舉例
api/v1/get-home-data 返回首頁用到的所有數(shù)據(jù)
這類API有一個非常不好的地址，只要業(yè)務需求變動宗苍，這個api就需要跟著變更稼稿。
自定義組合api
把當前用戶需要在第一時間內(nèi)容加載的多個接口合并成一個請求發(fā)送到服務端亿遂，服務端根據(jù)請求內(nèi)容，一次性把所有數(shù)據(jù)合并返回,相比于頁面級api渺杉，具備更高的靈活性，同時又能很容易的實現(xiàn)頁面級的api功能挪钓。
規(guī)范
地址：api/v1/batApi
傳入?yún)?shù)：
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]
返回數(shù)據(jù)
{status:0,msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}
Api共建平臺
RAP是一個GUI的WEB接口管理工具是越。在RAP中，您可定義接口的URL碌上、請求&響應細節(jié)格式等等倚评。通過分析這些數(shù)據(jù)，RAP提供MOCK服務馏予、測試服務等自動化工具天梧。RAP同時提供大量企業(yè)級功能，幫助企業(yè)和團隊高效的工作霞丧。
