軟件定義網絡基礎---REST API的設計規範

一：REST API的設計

REST API是基於HTTP協議進行設計的，由HTTP動詞+URI組成

（一）HTTP動詞

（二）資源的原型

文檔(Document)：

文檔是資源的單一表現形式；

集合(Collection)：

集合是資源的一個容器(目錄)，能夠向裏面添加 資源(文檔)；

倉庫(Store)：

客戶端管理的一個資源庫，能夠向倉庫中新增資源 或者刪除資源，或者從倉庫中獲取資源；

控制器(Controller)：

能夠執行一個方法，支持參數輸入，結果返 回。

（三）RESTful設計中URI命名的規範

資源命名規範：

 文檔(Document)類型的資源用　　    名詞單數命名
 集合(Collection)類型的資源用　  　名詞複數命名
 倉庫(Store)類型的資源用　　　　    名詞複數命名
 控制器(Controller)類型的資源用　　**動詞**命名

URI命名規範：

URI中有些字段能夠是變量，在實際使用中能夠按需替換，例如：
http://api.soccer.restapi.org/leagues/{leagueId}/teams/{teamId}/players/{playerId}
--- 其中：leagueId,teamId,playerId 是變量(數字，字符串等類型均可以)。

URI格式規範：

 URI中分隔符「/」通常用來對資源層級的劃分， 」/「不該該出如今URL的末尾；
 URI中儘可能使用連字符"-"代替下劃線"_"的使用
 例如： http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post
 URI中統一使用小寫字母
 URI中不要包含文件(或腳本)的擴展名
 例如：不要出來.php或者.json之類的後綴名。
 CRUD的操做不要體如今URI中

舉例：

URI的query字段：

 做爲查詢的參數補充，以標示一個惟一的資源
 做爲過濾條件使用，例如：
 GET /users?role=admin
 做爲資源列表分頁標示使用，例如：
 GET /users?pageSize=25&pageStartIndex=50

（四）HTTP響應狀態

REST API相關的響應狀態碼

 2xx：操做成功
 3xx：重定向
 4xx：客戶端錯誤
 5xx：服務器錯誤

經常使用狀態碼

 200 (「OK」) ：通常性的成功返回，不可用於請求錯誤返回；
 201 (「Created」) ：資源被建立；
 202 (「Accepted」) ：Controller控制類資源異步處理的返回，僅表示請求已經收到；
 204 (「No Content」) ：可能會出如今PUT、POST、DELETE的請求中；
 303 (「See Other」) ：返回一個資源地址URI的引用，但不強制要求客戶端獲取該
地址的狀態；
 400 (「Bad Request」) ：客戶端通常性錯誤返回, 其它4xx的錯誤，也能夠使用400，
具體錯誤信息能夠放在body中；
 401 (「Unauthorized」) ：認證錯誤；
 404 (「Not Found」) ：找不到URI對應的資源；
 500 Internal Server Error：服務器處理請求時發生了意外；
 503 Service Unavailable：服務器沒法處理請求，通常用於網站維護狀態。

（五）元數據設計

 HTTP Headers

 Content-Type ：body的數據格式，如Content-type: application/json，表示主類型是application，數據格式是json
 Content-Length ：body 數據體的大小
 Last-Modified ：資源最後被修改的時間戳
 ETag ：服務器端資源版本的標示
 Location ：在響應header中使用
 Cache-Control, Expires, Date ： 經過緩存機制提高接口響應性能

二：舉例---實際SDN控制器中REST API的設計

（一）Floodlight REST API

Floodlight北向API對外提供了四個模塊：OpenFlow流表、防火牆、ACL、多租戶網絡虛擬化。

ACL模塊的API

 查詢全部ACL規則：GET http://<controller_ip>:8080/wm/acl/rules/json
 添加ACL規則：POST http://<controller_ip>:8080/wm/acl/rules/json
 刪除一條ACL：DELETE http://<controller_ip>:8080/wm/acl/rules/json
 刪除全部ACL：GET http://<controller_ip>:8080/wm/acl/clear/json

使用POST動詞具體建立ACL或是使用DELETE動詞刪除某條ACL時，還須要在json中帶上須要傳輸的數據。例如以curl爲例：

curl -X POST -d
'{"src-ip":"10.0.0.1/32","dst-ip":"10.0.0.2/32","action":"deny"}'
http://<controller_ip>:8080/wm/acl/rules/json