# 3.5 RESTful Web API ## 3.5 RESTful Web API RESTful Web API就是按照REST方式設計的Web API。本章首先介紹Web API是什么，然后解釋RESTful的含義，最后給出進一步學習的建議。 ### Web API API即應用程序編程接口，比如\*nix操作系統提供的C語言接口的API可以完成創建進程、讀取系統時間等各種操作。Web API也是同樣，只不過不是直接調用某個代碼庫里的函數，而是通過HTTP來調用。一個簡單的Web API調用的例子如下： ``` GET /compute/sum?x=1&y=2 HTTP/1.1 Host: www.example.com ``` 假設www.example.com提供一個加法運算Web API ``` GET /compute/sum ``` 它接受兩個參數x和y，通過[URL](url.html)的查詢（query）部分傳遞。上面的代碼通過HTTP調用了它，并傳給它兩個參數 ``` x=1&y=2 ``` www.example.com的一個可能的回應是： ``` HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 1 3 ``` 這個簡單的例子已經說明了Web API的本質：客戶端請求服務器對某種資源進行某種操作，通過HTTP協議發送請求以及請求的參數，并得到結果。在這個例子中，資源就是由[Request URI](request.html#request-line) ``` /compute/sum ``` 所代表的服務器上的運算能力。 ### RESTful RESTful就是具有REST風格的意思。REST是**Representational State Transfer**的簡稱，一個難以顧名思義的名詞。 其實它也不是那么難以理解。 首先我們要搞清楚什么是*representation*。Representation就是“代表”的意思，比如在奧運會上運動員代表著國家，在人大會議上人大委員代表著人民，等等。在Web的世界里，我們用URI代表一個資源。比如，在前面的Web API的例子里， ``` /compute/sum ``` 就代表著www.example.com上的一種計算資源。資源可以是任何事物[1](#fn_1)，URI就是它的代表。 明白了representation是“代表”，就不難明白Representational State是指這種代表的狀態，實際上就是服務器上的資源的狀態。比如說，我們用/users代表網站的注冊用戶，那么這個資源的狀態可以是數據庫里注冊用戶表下的數據的狀態；當我們新增／刪除／更改用戶時，資源的狀態就發生了改變——這就是Representational State Transfer。 ### RESTful Web API 在具體設計上，RESTful Web API強調利用HTTP方法（Request Method）的語義來定義資源狀態轉換的各種操作。一個典型的例子如下： ``` GET /users ``` 獲取用戶列表。 ``` POST /users ``` 新增用戶。 ``` GET /users/:id ``` 獲取以:id標識的用戶。 ``` PATCH /users/:id ``` 更新以:id標識的用戶。 ``` DELETE /users/:id ``` 刪除以:id標識的用戶。 以上GET、POST、PATCH和DELETE都是HTTP方法，其中PATCH有時也以PUT方法代替（但它們是有差別的）。有些貫徹了REST的Web開發框架，如Ruby on Rails，會自動為你生成類似上面的代碼。 ### 進一步了解 以上就是關于REST的一點“Hello, World!”級別的介紹。REST內涵深刻，實現方式上也有很多可以說的地方，限于篇幅，這里僅介紹了一些皮毛。對于有興趣的讀者，我推薦： - [《RESTful Web APIs》](http://shop.oreilly.com/product/0636920028468.do) 這本書全面介紹了RESTful Web API的概念和設計要點，循序漸進。 - [《RESTful Web Services Cookbook》](http://shop.oreilly.com/product/9780596801694.do) 如果你正在尋找某個關于RESTful設計的具體問題，例如“何時應該使用GET/POST/...方法”，“如何識別資源”等，這本書可以告訴你答案。 以上兩本書均由OReilly出版，也有中譯版。 > 1. 我們早在[HTTP - 客戶端請求](request.html)就提到過這一點，在[Web服務器 - 方法與資源](http_method_and_resource.html)一節也重申過，如果忘記了請重溫一下——資源是一個重要的抽象概念。[?](#reffn_1 "Jump back to footnote [1] in the text.")