一：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
原文地址：https://www.cnblogs.com/liujunjun/p/12230670.html
时间： 2024-11-08 04:11:14