RESTful API 命名指南

RESTful API 又叫 Web API, REST 是 representational state transfer 的簡寫。RESTful API 使用 HTTP 協定的 GET, PUT, POST, PATCH 等操作來定義程式接口。由于這四個操作在 HTTP 協定都有特定的含義，是以我們應該遵循它們的習慣性用法。

• GET 用來查詢
• PUT 來修改資源
• POST 用來增加資源或者執行控制指令

• PATCH 用來改變資源的某個屬性

  在實際應用中由于隻改變資源某個屬性的情形較少，是以很多情況下會直接使用 PUT 直接修改資源

這些操作都是針對資源 (resource) 的，為了讓使用者能夠直覺準确地了解 API 的使用，我們應該遵循以下約定：

資源名稱使用小寫

所有 API 都會操作某個資源，資源名稱應該是小寫的複數形式，比如 students。

• 如果是兩個單詞組成的資源名稱，我們使用減号 “-” 來連接配接這個兩個單詞，比如 student schools 寫作 student-schools。
• 如果是資源的子集則子集放在斜線後

示例

# 查詢所有學生
GET /students
# 查詢id=996的學生
GET /students/996
# 查詢男生
GET /students/male
# 查詢年紀15歲男生
GET /students/male?age=15
# 查詢學生的學校
GET /student-schools

# 增加學生
POST /students
# 修改id=996的學生的資訊
PUT /student/996
           

使用 JSON 來定義 body 資訊

比如在增加學生時把學生定義為

{
 "name": "Tom",
 "gender": "male".
 "age": 15
}
           

然後使用 POST 指令來增加資源

POST /students/
           

使用 POST 來執行控制指令

POST 除了可以用來增加資源，還被用來針對資源執行指令，比如：

# 激活ID=996的名聲賬号
POST /student/activate/996
           

上例中 activate 就是控制指令

使用 ProblemDetail 來定義傳回錯誤資訊

我們看到很多 API 都是自己定義錯誤資訊的傳回格式，其實早有錯誤格式的工業标準，這就是 RFC 7807 使用Problem Detail 來傳回錯誤資訊。

這是它的樣子：

// For example, an HTTP response carrying JSON problem details:

//  HTTP/1.1 403 Forbidden
//  Content-Type: application/problem+json
//  Content-Language: en
{
    "type": "https://example.com/probs/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "Your current balance is 30, but that costs 50.",
    "instance": "/account/12345/msgs/abc",
    "balance": 30,
    "accounts": ["/account/12345",
                 "/account/67890"]
}
           

上面的示例中 type, title, detail, instance 是标準選項，balance下面的資訊是自定義選項。幾乎每種主流程式設計語言都有支援這個标準的解決方案。