RESTful API 設計準則與實務經驗 | restful api優點
關於RESTfulAPI在以前幾篇骨灰級的文章中曾經有介紹過REST[1],接觸過Web開發的大大們多少都聽過、看過或夢到過RESTAPI,算是常聽到的技術名詞。那麼RESTful到底是什麼?其實RESTful並不是什麼獨特的技術規範,RESTful是一種「軟體架構風格」,這樣的解釋聽起來是不是很玄!?實務上要如何設計RESTAPI呢?開始之前,我們先回顧一下重要的RESTful-Triangle(REST金三角)概念:右邊這個三角形描述了以下三個重要的概念:Nouns名詞:用來定義你的網址URL,記住,每一個網路上的資源應該僅有一個唯一的識別位置,就像你的房子有獨一無二的...
關於 RESTful API在以前幾篇骨灰級的文章中曾經有介紹過 REST[1],接觸過 Web 開發的大大們多少都聽過、看過或夢到過 REST API,算是常聽到的技術名詞。那麼 RESTful 到底是什麼?其實 RESTful 並不是什麼獨特的技術規範,RESTful 是一種「軟體架構風格」,這樣的解釋聽起來是不是很玄!?實務上要如何設計 REST API 呢?開始之前,我們先回顧一下重要的 RESTful-Triangle (REST 金三角) 概念:
右邊這個三角形描述了以下三個重要的概念:
Nouns 名詞:用來定義你的網址 URL,記住,每一個網路上的資源應該僅有一個唯一的識別位置,就像你的房子有獨一無二的「住址」一樣。Verbs 動詞:描述了對 Nouns 名詞 (資源 URL) 的操作動作,在 HTTP 1.1 的實作當然就是 HTTP Method。比如用 GET 取得文章內容、用 DELETE 刪除文章等等行為。Content Types 資源呈現方式:比如取得某一個 URL 文章的 HTML 格式、或者 XML 格式,同樣的 URL 資源可以有不同型態的表現方式。建議在設計 API 規格時,同時思考上述的設計原則,好讓 API 設計更接近 REST 精神。
這幾年參與並重構了一些不同的系統,也認識一些很棒的開發團隊,大部分對於 REST 的接受程度都相當樂觀。但 RESR 應用在實務的 API 設計上,常遭遇不同複雜的業務情境,不一定能夠將 API 設計的很 RESTful,在看過不少 REST API 規格文件之後,歸納了幾點常犯的錯誤,順便警惕自己未來不要踩到雷了。
用了 GET, POST, PUT, DELETE 不等於 RESTful API?這類的錯誤蠻常遇見的,常常只是把刪除動作透過 DELETE 進行呼叫,而缺少對 URL 的設計與資源定義,URL 中也常常出現動詞 (描述行為),舉個錯誤的例子:
上傳文章 POST /api/article/upload
刪除文章 DELETE /api/article/remove
看出來問題在哪了嗎?就是 URL 的設計問題,比較正確的 REST API 會設計一個唯一的 URL 來表示...