almost 4 years ago

關於 REST 的基本介紹可以看 ihower 的什麼是REST跟RESTful?,在這裡我們將專注於介紹 RESTful API 一些慣用設計原則。

好處

RESTful API 帶給開發人員的好處之一就是降低負擔,只要開發一次就能通吃各類客戶端,因為只要支援 HTTP 即可,不用管 application 類型是 web 還是 mobile ,也不用管客戶端用哪種語言開發。

URL schemes

常見的 schemes ,注意在 production 中務必使用 SSL

 https://api.yoursite/
 https://yoursite/api/

Versioning

API 應該有版號控管,這樣使用舊版 API 的人還是可以繼續使用,方便達到 backward compatibility。一種做法是在 URL 中放置版號,例如 Google+ 的 API:

https://www.googleapis.com/plus/v1/people/{userId}

有些人覺得將版號放在 Accept header 比較好,例如 GitHub 的 API:

Accept: application/vnd.github.v3+json

RESTful URLs

URL 代表一種 resource ,一個很重要的慣例就是不能有動詞,最好使用複數的名詞,動詞交給 HTTP methods 解決,如此一來提供了一致性,讓使用 API 的人容易掌握。下面是一些基本的 CRUD 範例:

Endpoint 意義
GET /v1/servers 列出所有 servers
GET /v1/servers/1 獲得特定 server
GET /v1/servers/1/ifs/eth0 獲得特定 server 上 eth0 的資訊
POST /v1/servers 新增 server
PUT /v1/servers/1 更新特定 server (完全取代)
PATCH /v1/servers/1 更新特定 server (部分取代)
DELETE /v1/servers/1 刪除特定 server

複雜一點的例子

Endpoint 意義
POST /v1/servers/1/action 對特定 server 做操作,例如重開機
GET /v1/servers?limit=10 列出十台 servers

有些操作並不適用於單純的 CRUD ,如上表第一個例子,可以用個 sub-resource ,然後將操作格式寫在 request body 裡。

{
    "reboot": {
        "type": "SOFT"
    }
}

Data Format

目前 JSON 是最通用的格式, XML 沒什麼人在用了。

Further Reading

Best Practices for Designing a Pragmatic RESTful API
Consumer-Centric API Design

← 用 Flask 打造 RESTful API FLASK 簡介 - Hello World →
 
comments powered by Disqus