一：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