软件定义网络基础---REST API的设计规范

xiaouncle 2020-01-23

一:REST API的设计

REST API是基于HTTP协议进行设计的,由HTTP动词+URI组成

软件定义网络基础---REST API的设计规范

(一)HTTP动词

软件定义网络基础---REST API的设计规范

(二)资源的原型

文档(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中

举例:

软件定义网络基础---REST API的设计规范

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

相关推荐