NO IMAGE

前言

近十年,前端高速發展,整個網際網路應用經歷了從輕客戶端到重客戶端的變化,隨著前端規模越來越大,互動越來越複雜,前後端分離的設計開始流行。

移動網際網路時代的到來,前端開始泛指各種終端和 web 前端,服務端為多終端提供服務已然成常態。

前後端分離後,前端和後端通過雙方協商好的 API 進行互動,所以設計一套友好的 API 尤其重要。

RESTful 就是目前最流行的前後端互動 API 設計正規化。

RESTful 釋義

顧名思義,先看一下 RESTful 的單詞拆解:

RESTful = Resources Representation State Transfer ful

我的理解是, RESTful 是指具有 資源表現層狀態轉換 的架構設計。

資源(Resources)

資源,是指服務端向外提供的服務實體。

資源是一個抽象的概念,可以是應用程式物件、資料庫記錄、演算法等等。每一個資源用一個 URI 來唯一標識,客戶端通過這個標識對資源進行訪問、操作或請求服務。

表現層(Representation)

表現層,是指資源的表現形式。

一個資源可以有多種表現形式。例如,文字資料可以用 XML 格式、JSON 格式表現,甚至可以用二進位制格式表示;圖片可以用 JPG 格式表現,也可以用 PNG 格式表現。

狀態(State)

狀態,是指資源的某種狀態。

一個資源可能有多種狀態。例如,資源空閒的、佔用的、共享的、存在的、不存在的等。

轉化(Transfer)

轉化,是指對資源的操作行為。

轉化的行為包括兩種:

資源表現層的轉化
資源狀態的轉化

ful

字尾是英文的一種重要構詞法,通過字尾常常可以判斷出一個詞的詞性。

ful 表形容詞,意為“… 的”、“具有 … 的”。

小結

RESTful 是一種抽象的、與具體程式語言和網路協議無關的網路服務系統的架構樣式。

它把在伺服器端的資料和功能設計成各種的資源,並且通過 URI 定位資源、轉化資源表現和狀態的一種服務架構設計。

RESTful WEB

REST 指的是一組架構約束條件和原則。滿足這些約束條件和原則的應用程式或設計就是 RESTful。

目前 RESTful 應用最多的是在 web 服務,在 RESTful Web 服務中,每個資源都有一個地址(URL)。資源是方法呼叫的目標,方法列表對所有資源都是一樣的。這些方法是 Http 標準方法,如 HTTP GET、POST、PUT、DELETE 等。

下面來描述一下 RESTful Web API 的一些設計原則。

通訊協議

資料傳輸,安全第一。

HTTPS 協議要優於 HTTP 協議。

API 的根 URL

API 的根 URL 很重要,它應該設計成可以輕鬆區別於其他非 API 的 URL。

最好的做法是將 API 部署在專有的域名下。

https://api.example.com

退而求其次,分配一個域名一級目錄給 API。

https://example.org/api/

版本資訊

為了 API 演變和相容,為 API 加入版本資訊是明智之舉。

應該為 API 設定版本號,並把版本號資訊加入到 API 的根 URL 的下一級路徑。

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

https://example.org/api/v1/

URL 末端

API 的根 URL 版本資訊 URL 末端 = 資源位置

URL 末端最終明確指定了一個資源或一種資源的集合。URL 末端中不應該出現動詞,只能是名詞。如果該資源可以取其集合,對應的名詞應該採用複數形式。

舉個例子,有一組 API 提供公司員工的資訊。

那麼,獲取所有員工資訊,末端應該設計成 /employees

獲取員工編號 007 員工的資訊,末端應該設計成 /employees/007

操作資源

資源的操作無外乎增、刪、改、查,對應即是 HTTP 的各個操作方法。

HTTP的操作方法在 RESTful 中有各自的語義,理解它們的語義至為重要。

方法語義例子說明
GET選擇、獲取GET /employees/007

返回結果

對於不同操作方法和操作物件(集合或個體),伺服器返回的結果應該符合以下規範。

示例返回
GET /collection返回資源物件的列表(陣列)
GET /collection/resource返回單個資源物件
POST /collection返回新生成的資源物件
PUT /collection/resource返回完整的資源物件
PATCH /collection/resource返回完整的資源物件
DELETE /collection/resource返回一個空文件

另外,返回的資料格式(Representation)應該儘量使用JSON。

最後

在 RESTful WEB 的實現中,使用 URL 定位資源,HTTP 方法操作資源,使得語義明確、結構清晰、易於理解和擴充套件。

RESTful 的這些優勢,使得它成為了目前最流行的一種網際網路服務架構。

附錄

該文主要參考:

Principles of good RESTful API Design
理解RESTful架構
RESTful API 設計指南