restfull api 介面規範

1 這種介面可以根據客戶端的要求型別返回不同的型別的表現形式，比如返回json，返回xml，返回純文字。

2 這種介面不同的操作就得用不同的方法 get post delete put

get（select）：從伺服器取出資源（一項或多項）。

還有兩個不常用的http動詞。

3 這種介面不可以在 url 中出現動詞。

4 這種介面版本資訊應該放到標頭檔案中。

5 可以根據條件過濾資訊：

如果記錄數量很多，伺服器不可能都將它們返回給使用者。api應該提供引數，過濾返回結果。

下面是一些常見的引數。

6 狀態碼：

伺服器向使用者返回的狀態碼和提示資訊，常見的有以下一些（方括號中是該狀態碼對應的http動詞）。

7 錯誤處理：

如果狀態碼是4xx，就應該向使用者返回出錯資訊。一般來說，返回的資訊中將error作為鍵名，出錯資訊作為鍵值即可。

8返回結果：

針對不同操作，伺服器向使用者返回的結果應該符合以下規範。

9 連線api

比如，當使用者向api.example.com的根目錄發出請求，會得到這樣乙個文件。

}

上面**表示，文件中有乙個link屬性，使用者讀取這個屬性就知道下一步該呼叫什麼api了。rel表示這個api與當前**的關係（collection關係，並給出該collection的**），href表示api的路徑，title表示api的標題，type表示返回型別。

hypermedia api的設計被稱為hateoas。github的api就是這種設計，訪問api.github.com會得到乙個所有可用api的**列表。

從上面可以看到，如果想獲取當前使用者的資訊，應該去訪問api.github.com/user，然後就得到了下面結果。

上面**表示，伺服器給出了提示資訊，以及文件的**。

10 其他：

（1）api的身份認證應該使用oauth 2.0框架。

（2）伺服器返回的資料格式，應該盡量使用json，避免使用xml。

11 無狀態性：

restful只要維護資源的狀態，而不需要維護客戶端的狀態。對於它來說，每次請求都是全新的，它只需要針對本次請求作相應的操作，不需要將本次請求的相關資訊記錄下來以便用於後續來自相同客戶端請求的處理。

web api只會定義根據具體頁碼的資料查詢定義相關的操作，當前返回資料的頁碼由客戶端來維護。

第一種貌似很「智慧型」，其實就是一種畫蛇添足的作法，因為它破壞了web api的無狀態性。設計無狀態的web api不僅僅使web api自身顯得簡單而精煉，還因減除了針對客戶端的「親和度（affinty）」使我們可以有效地實施負載均衡，因為只有這樣集群中的每一台伺服器對於每個客戶端才是等效的。

restfull api 介面 規範