软件定义网络基础---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