一:什么是REST API
REST API是北向接口的主流设计方式
API是应用程序编程接口,是预先定义好的函数,可以供应用程序或开发人员访问调用
REST (Representational State Transfer,表述化状态转移)首次出现在2000 年 Roy Thomas Fielding 的博士论文中,指的是一组架构约束条件和原则。
1.REST和API关系
满足REST约束条件和原则的设计规范或者架构风格,我们称之为RESTful,遵循RESTful设计的API就是REST API
2.RESTful
RESTful并不是专门为SDN提出的,而是专门针对Web应用中HTTP使用中出现的一些问题提出的,由于HTTP协议的使用很不规范、随意、混乱
URL的设计缺乏规范性
HTTP的动词使用不当
HTTP的返回状态码使用不规范等
Restful正是针对HTTP中上述问题而提出的
显得更加规范和简洁
3.REST中的几个重要概念
资源:REST是面向资源的设计,比如在普通的博客应用中,资源可能是包括了用户、博文或者评论等 在SDN中,资源可能是链路、交换机、流表等。
资源标识符:URI是统一资源标示符,URL是统一资源定位符。URL是URI的子集,或者说是一种具体实现,对于REST API来说一个资源对应唯一的一个URI,REST通过URI来暴露资源,URI的设计的合理性和规范性十分重要。
4.REST的约束条件与原则
客户-服务器(Client-Server)约束---实现解耦:用户接口和数据存储的分离;---通过客户端用户接口和服务器数据存储的分离,提高了客户端的便捷性,也提高了服务端的可伸缩性。由于实现了解耦,就能够允许客户端和服务端分组优化,彼此之间不受影响。
无状态(Stateless):要求来自客户端的每一个请求必须包含服务器处理该请求所需的所有信息; --- 提高了可见性和可靠性,由于服务器是无状态的,能够很方便的实现水平扩展,提高了可扩展性。
在该流程中后面的每一个状态都依赖于前面的状态,没有一个URL可以直接查询到成绩。
而在RESTful的架构中,可以直接定位到服务器的资源,不依赖于服务器的会话状态,因此是无状态。
缓存(Cache):要求一个请求的响应中的数据标记为是否可缓存;如果可以,客户端可以重用相同请求的响应数据---减少了CS交互次数,提高了效率。
统一接口(Uniform Interface):核心特征,强调组件之间要有一个统一的接口; --- CS之间通信的方法必须是统一化的,例如标准的HTTP动作。
分层系统(Layered System): 限制组件的行为,将架构分为若干等级的层;允许服务器和客户端之间的中间层,例如反向代理、API网关,可以代替服务器对客户端的请求进行回应,而对客户端而言是透明的,提高了系统的可扩展性,也增加了系统的复杂性。
按需代码(Code-On-Demand,可选):服务器可以提供一些代码或者脚本并在客户的运行环境中执行。
二:REST API的设计规范
REST API是基于HTTP协议进行设计的,由HTTP动词+URI组成。HTTP动词描述操作;URI是标识资源。
1.HTTP动词:
2.资源的原型:
文档(Document):
文档是资源的单一表现形式;
集合(Collection):
集合是资源的一个容器(目录),可以向里面添加 资源(文档);
仓库(Store):
客户端管理的一个资源库,可以向仓库中新增资源 或者删除资源,或者从仓库中获取资源;
控制器(Controller):
可以执行一个方法,支持参数输入,结果返回。
3.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
4.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:服务器无法处理请求,一般用于网站维护状态。
5.元数据设计:
Content-Type :body的数据格式,如Content-type: application/json,表示主类型是application,数据格式是json
Content-Length :body 数据体的大小
Last-Modified :资源最后被修改的时间戳
ETag :服务器端资源版本的标示
Location :在响应header中使用
Cache-Control, Expires, Date : 通过缓存机制提升接口响应性能