閒聊 | web api
傳說C語言風格(C#/Java/JavaScript…)程序員依其信仰分為兩大派,自古以來不共戴天:依我的觀點,寫WebAPI的程序員也分成兩派,RESTful派跟非REST派。我屬於後者,是非主流的少數派。前幾天跟同事聊到WebAPI是否一定要RESTful,三言兩語說不清,寫篇文章梳理思緒好了。RESTfulAPI是指實踐RESTRepresentationalStateTransfer[1]精神的API設計風格,其核心精神在於借用HTTP協定做為基礎,讓API規格簡單一致,大致有以下特色:透過URI指定要存取或操作的資源可使用QueryString,但只應拿來傳遞額外過濾條件或參數,不應包含識別資源的鍵值...
傳說 C 語言風格(C#/Java/JavaScript…)程序員依其信仰分為兩大派,自古以來不共戴天:
依我的觀點,寫 WebAPI 的程序員也分成兩派,RESTful 派跟非 REST 派。我屬於後者,是非主流的少數派。
前幾天跟同事聊到 Web API 是否一定要 RESTful,三言兩語說不清,寫篇文章梳理思緒好了。
RESTful API 是指實踐 REST Representational State Transfer[1] 精神的 API 設計風格,其核心精神在於借用 HTTP 協定做為基礎,讓 API 規格簡單一致,大致有以下特色 :
透過 URI 指定要存取或操作的資源 可使用 QueryString,但只應拿來傳遞額外過濾條件或參數,不應包含識別資源的鍵值 使用 HTTP 方法 POST、GET、PUT、DELETE 對應到建立、讀取、更新、刪除等動作。 也有人主張 PUT 是 Relace (Create 或 Update),另外增加 PATCH 用於部分更新( Partial Update ) 透過 Accept Header 指明可接收的內容格式,例如:XML 或是 JSON 伺服器透過 HTTP 狀態碼回傳執行結果,例如:200 成功、401 存取被拒、404 找不到資源、500 伺服器錯誤而 REST 概念的提出者 Roy Fielding[2] 是 HTTP 規範的主要作者及 Apache HTTP Server 專案的發起人之一,這也是讓 RESTful API 風格備受推崇的原因之一。
延伸閱讀
採用 RESTful API 最大的好處是風格統一,API 名稱簡潔(不會冒出一堆 QueryThese、UpdateThat、DeleteBlah,動詞隱藏在 HTTP Method ),靠直覺及經驗就能快速上手;除錯時也可由 URL、HTTP 方法及傳回狀態直接解析各項操作的意義及結果。多年來,RESTful 設計已是 Web API 設計的主流,例如:ASP.NET MVC Web API 即是走 RESTful 風格,當在專案新增繼承 ApiController 的 API 類別,預設需實作 Get()、Post()、Put()、Del...