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

 

猜你喜欢

转载自www.cnblogs.com/ssyfj/p/11654648.html