RESTful API 規範(一)
一,簡介
DRF 即Django rest framework
二,rest 規範
1 協議
API 與使用者通訊,總是使用https協議
2 域名
1) 應儘量將API 部署在域名下(這種情況會存在跨域問題)
https://api.example.com
2)如果確定API很簡單,不會有進一步擴充套件,可以考慮放在主域名下
https://example.org/api/
3 版本
應儘量將版本放到URL
https://api.example.com/v1/
ps:另一種做法是將版本放在HTTP頭資訊中,但不如放入URL方便和直觀
4 路徑
路徑又稱“終點”,表示API的具體網址。
在RESTful框架中,每個網址代表一種資源,所以網址中不能有動詞,只有名稱,而且所用的名詞往往與資料庫的表格名對應,
一般來說,資料庫中的表都是同種記錄的“集合”,所以API種的名詞應該使用複數。
例子:
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
5 HTTP 請求方式
對資源的具體操作型別,由HTTP請求方式表示
常用的HTTP請求方式有五個(括號種為對應的SQL命令):
GET(SELECT):從伺服器取出資源(一項或多項)。
POST(CREATE):在伺服器新建一個資源。
PUT(UPDATE):在伺服器更新資源(客戶端提供改變後的完整資源)。
PATCH(UPDATE):在伺服器更新資源(客戶端提供改變的屬性)。
DELETE(DELETE):從伺服器刪除資源。
還有兩個不常用的HTTP動詞。
HEAD:獲取資源的元資料。
OPTIONS:獲取資訊,關於資源的哪些屬性是客戶端可以改變的。
6 過濾資訊(Filtering)
如果記錄數量很多,伺服器不可能都將他們返回給使用者,API應提供引數,過濾返回結果
例子:
https://api.example.com/v1/zoos?limit=10:指定返回記錄的數量
https://api.example.com/v1/zoos?offset=10:指定返回記錄的開始位置
https://api.example.com/v1/zoos?page=2&per_page=100:指定第幾頁,以及每頁的記錄數
https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回結果按照哪個屬性排序,以及排序順序
https://api.example.com/v1/zoos?animal_type_id=1:指定篩選條件
7 狀態碼
伺服器向用戶返回的狀態碼和提示資訊,常見的有如下:
200 OK - [GET]:伺服器成功返回使用者請求的資料,該操作是冪等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:使用者新建或修改資料成功。
202 Accepted - [*]:表示一個請求已經進入後臺排隊(非同步任務)
204 NO CONTENT - [DELETE]:使用者刪除資料成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:使用者發出的請求有錯誤,伺服器沒有進行新建或修改資料的操作,該操作是冪等的。
401 Unauthorized - [*]:表示使用者沒有許可權(令牌、使用者名稱、密碼錯誤)。
403 Forbidden - [*] 表示使用者得到授權(與401錯誤相對),但是訪問是被禁止的。
404 NOT FOUND - [*]:使用者發出的請求針對的是不存在的記錄,伺服器沒有進行操作,該操作是冪等的。
406 Not Acceptable - [GET]:使用者請求的格式不可得(比如使用者請求JSON格式,但是隻有XML格式)。
410 Gone -[GET]:使用者請求的資源被永久刪除,且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個物件時,發生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]:伺服器發生錯誤,使用者將無法判斷髮出的請求是否成功。
- 狀態碼的完全列表參見這裡。
8 錯誤處理
如果狀態碼是4xx,就應該向使用者返回錯誤資訊。一般來說,返回的資訊中將error作為鍵值
{
error: "Invalid API key"
}
9 返回結果
針對不同的操作,伺服器向用戶返回的結果應該符合如下規範:
GET /collection:返回資源物件的列表(陣列)
GET /collection/resource:返回單個資源物件
POST /collection:返回新生成的資源物件
PUT /collection/resource:返回完整的資源物件
PATCH /collection/resource:返回完整的資源物件
DELETE /collection/resource:返回一個空檔案
10 Hypermedia API
RESTful API 最好做到Hypermedia,即返回結果中提供連結,連向其他API方法,如:
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
11其他
(1)API的身份認證應該使用OAuth 2.0框架。
(2)伺服器返回的資料格式,應該儘量使用JSON,避免使用XML。