REST API
REST=Representational State Transfer(表述化状态转移)
REST是一组架构约束条件和原则,满足REST设计原则的设计规范或架构风格叫RESTful,遵循RESTful设计的API叫REST API。REST是为了规范HTTP请求而提出的(如URL规范)
REST是面向资源的设计,一个资源对应唯一的一个URI(通过URI来暴露资源),在web中资源标识符的实例就是URI(包含URL和URN两种形式)
eg:DELETE /student/10
REST的约束条件:
- 客户-服务器模型:实现解耦(客户端、服务器各干各的)
- 无状态:要求来自客户端的每一个请求必须包含服务器处理该请求所需要的所有信息
- 缓存:要求一个请求的响应中的数据标记为是否可缓存
- 统一接口:客户和服务器之间通信的方法是统一化的,如标准的HTTP动作GET、POST、PUT、DELETE等
- 分层系统:允许服务器和客户端之间的中间层(如反向代理、网关),对于客户端来说都是透明的
- (按需代码)
REST API的设计规范:【HTTP动词+URI】
①HTTP动词用于标识操作,常用的有HEAD,GET,POST,PATCH,PUT,DELETE
②URI用于标识资源,资源的原型有文档、集合、仓库、控制器
集合是资源的一个容器(目录),可以向里面添加资源(文档);控制器可以执行一个方法,支持参数输入,结果返回
URI命名规范:
文档类型:名词单数
集合、仓库类型:名词复数
控制器类型:包含动词的词语
字段可以是变量,在实际使用中可以按需替换,变量写在{}
中
URI格式规范:
分隔符/
一般用于对资源层级的划分,/
不应该出现在URL的末尾
尽量使用连字符-
代替下换线_
的使用
统一使用小写字母
不要包含文件(或脚本)的扩展名
CRUD操作不能体现在URI中
URI的query字段作为查询的参数补充,以标示一个唯一的资源,可以作为过滤条件使用
需要设置HTTP的响应状态码:
2xx:操作成功;3xx:重定向;4xx:客户端错误;5xx:服务端错误
常用的:200,201,400,401,404,500
元数据设计:HTTP头部设置元数据字段格式,如Content-Type、Content-Length等字段
举例(SDN中ryu控制器提供的ACL模块的北向REST API):
//这个就是一个REST API,C端根据这个API进行传输请求
//后面的这个URL就是S上的资源地址,POST就是操作
//POST动作、DELETE动作还需要在JSON中写入需要传输的数据,见下面的请求demo
REST API : POST http://<controller_ip>:8080/wm/acl/rules/json
//crul命令是一个http请求工具(-X:请求协议,-d:POST内容)
crul -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
P.S.
- REST API是SDN北向接口的主要实现标准
- URI是统一资源标识符,URL是统一资源定位符,URL是URI的子集
- 元数据:表述数据的数据上(如媒体类型、最后修改时间、源链接等)
- 无状态:每一个步骤不依赖于前一个步骤(直接定位到服务器的资源,不依赖于客户端-服务器的会话状态)