一、版本（Versioning）

1. 作法1：
   應(yīng)該將API的版本號(hào)放入U(xiǎn)RL款慨。

https://api.example.com/v1/

作法2：
將版本號(hào)放在HTTP頭信息中库倘，但不如放入U(xiǎn)RL方便和直觀。

Github采用這種做法毡咏。

二、路徑（Endpoint）

路徑又稱"終點(diǎn)"（endpoint）逮刨，表示API的具體網(wǎng)址呕缭。
在RESTful架構(gòu)中，每個(gè)網(wǎng)址代表一種資源（resource）修己，所以網(wǎng)址中不能有動(dòng)詞恢总，只能有名詞，而且所用的名詞往往與數(shù)據(jù)庫的表格名對(duì)應(yīng)睬愤。一般來說片仿，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)尤辱。
舉例來說砂豌，有一個(gè)API提供動(dòng)物園（zoo）的信息，還包括各種動(dòng)物和雇員的信息光督，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣阳距。

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

三、HTTP動(dòng)詞
對(duì)于資源的具體操作類型结借，由HTTP動(dòng)詞表示筐摘。
常用的HTTP動(dòng)詞有下面五個(gè)（括號(hào)里是對(duì)應(yīng)的SQL命令）。

GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
POST（CREATE）：在服務(wù)器新建一個(gè)資源咖熟。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）圃酵。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務(wù)器刪除資源球恤。

還有兩個(gè)不常用的HTTP動(dòng)詞辜昵。

HEAD：獲取資源的元數(shù)據(jù)。
OPTIONS：獲取信息咽斧，關(guān)于資源的哪些屬性是客戶端可以改變的堪置。

下面是一些例子。

GET /zoos：列出所有動(dòng)物園
POST /zoos：新建一個(gè)動(dòng)物園
GET /zoos/ID：獲取某個(gè)指定動(dòng)物園的信息
PUT /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的全部信息）
PATCH /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的部分信息）
DELETE /zoos/ID：刪除某個(gè)動(dòng)物園
GET /zoos/ID/animals：列出某個(gè)指定動(dòng)物園的所有動(dòng)物
DELETE /zoos/ID/animals/ID：刪除某個(gè)指定動(dòng)物園的指定動(dòng)物

三张惹、狀態(tài)碼（Status Codes）

服務(wù)器向用戶返回的狀態(tài)碼和提示信息舀锨，常見的有以下一些（方括號(hào)中是該狀態(tài)碼對(duì)應(yīng)的HTTP動(dòng)詞）。

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)求是否成功。

三轩褐、錯(cuò)誤處理（Error handling）

如果狀態(tài)碼是4xx椎咧，就應(yīng)該向用戶返回出錯(cuò)信息。一般來說，返回的信息中將error作為鍵名勤讽，出錯(cuò)信息作為鍵值即可蟋座。

{ error: "Invalid API key"}

四、返回結(jié)果

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