@(python之路)[restful規(guī)范]
restful規(guī)范

什么是RESTful

• rest與技術(shù)無關(guān)，他只是代表代表一種架構(gòu)風(fēng)格，rest是representational state transfer的簡稱，中文翻譯為“表征狀態(tài)轉(zhuǎn)移”；
• rest是從資源的角度來審視整個(gè)網(wǎng)絡(luò)，它可以通過URL獲取后端數(shù)據(jù)，前端做渲染，可以把后端看作為是一個(gè)資源；
• 面向自資源架構(gòu)：ROA:Resource Oriented Architecture

RESTful API設(shè)計(jì)

1. api與用戶的通信協(xié)議，最好使用HTTPs協(xié)議。

詳情請(qǐng)看這里

2.域名

• https://api.example.com
• https://example.org/api

盡量將API部署在專用域名但是這樣做也會(huì)存在跨域風(fēng)險(xiǎn)。
第二種方式就比較簡單了。

3.版本

我們api的版本最好是要標(biāo)識(shí)出來，一般標(biāo)識(shí)的地方，可以在域名中標(biāo)；也可以在請(qǐng)求頭標(biāo)識(shí)。但是在跨域時(shí)會(huì)引發(fā)發(fā)送多次的請(qǐng)求頭。

• url: 如：https://api.example.com/v1
• url: 如：https//www.example.com/api/v1
• 存放在請(qǐng)求頭中。

4.路徑，命名方式均使用名詞表示（可以是復(fù)數(shù)）

• https://api.example.com/v1/zoos
• https://api.example.com/v1/animals
• https://api.example.com/v1/employees

method

• GET: 獲取用戶
• POST: 增加用戶
• PUT:修改用戶
• DELETE:刪除用戶

5.過濾，通過url上傳參數(shù)的形式傳遞搜索條件

• https://api.example.com/v1/zoos?limit=10：指定返回記錄的數(shù)量
• https://api.example.com/v1/zoos?offset=10：指定返回記錄的開始位置
• https://api.example.com/v1/zoos?page=2&per_page=100：指定第幾頁，以及每頁的記錄數(shù)
• https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序
• https://api.example.com/v1/zoos?animal_type_id=1：指定篩選條件

6.狀態(tài)嗎

200 OK - [GET]：服務(wù)器成功返回用戶請(qǐng)求的數(shù)據(jù)，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。
202 Accepted - [*]：表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請(qǐng)求有錯(cuò)誤，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌、用戶名、密碼錯(cuò)誤）。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯(cuò)誤相對(duì)），但是訪問是被禁止的。
404 NOT FOUND - [*]：用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄，服務(wù)器沒有進(jìn)行操作，該操作是冪等的。
406 Not Acceptable - [GET]：用戶請(qǐng)求的格式不可得（比如用戶請(qǐng)求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用戶請(qǐng)求的資源被永久刪除，且不會(huì)再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯(cuò)誤，用戶將無法判斷發(fā)出的請(qǐng)求是否成功。

更多看這里：http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

7.錯(cuò)誤處理，狀態(tài)碼是4xx時(shí)，返回錯(cuò)誤信息，error當(dāng)作key

{
	error:"Invalid API key",

}

8.返回結(jié)果，針對(duì)不同的操作，服務(wù)器應(yīng)該向用戶返回結(jié)果應(yīng)符合以下規(guī)范。

GET /collection：返回資源對(duì)象的列表（數(shù)組）
GET /collection/resource：返回單個(gè)資源對(duì)象
POST /collection：返回新生成的資源對(duì)象
PUT /collection/resource：返回完整的資源對(duì)象
PATCH /collection/resource：返回完整的資源對(duì)象
DELETE /collection/resource：返回一個(gè)空文檔

9.Hypermedia API，RESTful API最好做到Hypermedia，即返回結(jié)果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應(yīng)該做什么。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

摘自：http://www.rzrgm.cn/wupeiqi/articles/7805382.html