一、REST API

REST、RESTful、REST API

API： 是应用程序编程接口，是预先定义好的函数，可以供应用程序或开发人员访问调用
REST（Representational State Transfer，表述化状态转移）：指的是一组架构约束条件和原则。
RESTful：满足REST约束条件和原则的设计规范或者架构风格
REST API：是北向接口的主流设计方式，遵循RESTful设计的API

为什么需要RESTful

RESTful并不是专门为SDN提出的，而是专门针对Web应用中HTTP使用中出现的一些问题提出的，由于HTTP协议的使用很不规范、随意、混乱
URL的设计缺乏规范性
HTTP的动词使用不当
HTTP的返回状态码使用不规范等
Restful正是针对HTTP中上述问题而提出的

rest api和api举例 rest api规范_HTTP


rest api和api举例 rest api规范_HTTP_02

REST中的几个重要概念

rest api和api举例 rest api规范_REST_03


资源（resource）

比如在普通的博客应用中，资源可能是包括了用户、博文或者评论等
在SDN中，资源可能是链路、交换机、流表等

资源标识符（resource identifiers）

URI是统一资源标示符，URL是统一资源定位符。URL是URI的子集，或者说是一种具体实现
对于REST API来说一个资源对应唯一的一个URI，REST通过URI来暴露资源，URI的设计的合理性和规范性十分重要

REST的约束条件与原则

  • 客户-服务器（Client-Server）：用户接口和数据存储的分离；---通过客户端用户接口和服务器数据存储的分离，提高了客户端的便捷性，也提高了服务端的可伸缩性。由于实现了解耦，就能够允许客户端和服务端分组优化，彼此之间不受影响
  • 无状态（Stateless）：要求每一个请求必须包含服务器处理该请求所需的所有信息；--- 提高了可见性和可靠性，由于服务器是无状态的，能够很方便的实现水平扩展,提高了可扩展性。 在RESTful的架构中，可以直接定位到服务器的资源，不依赖于服务器的会话状态，因此是无状态
  • 缓存（Cache）：要求一个请求的响应中的数据标记为是否可缓存；如果可以，客户端可以重用相同请求的响应数据---减少了CS交互次数，提高了效率
  • 统一接口（Uniform Interface）：核心特征，强调组件之间要有一个统一的接口；--- CS之间通信的方法必须是统一化的，例如标准的HTTP动作
  • 分层系统（Layered System）：限制组件的行为，将架构分为若干等级的层；允许服务器和客户端之间的中间层，例如反向代理、API网关，可以代替服务器对客户端的请求进行回应，而对客户端而言是透明的，提高了系统的可扩展性，也增加了系统的复杂性
  • 按需代码（Code-On-Demand，可选）：服务器可以提供一些代码或者脚本并在客户的运行环境中执行。

REST API的设计

REST API是基于HTTP协议进行设计的，由HTTP动词+URI组成，HTTP动词描述操作；URI是标识资源。

HTTP动词

rest api和api举例 rest api规范_rest api和api举例_04

资源的原型

  • 文档(Document)：文档是资源的单一表现形式；
  • 集合(Collection)：集合是资源的一个容器(目录)，可以向里面添加资源(文档)；
  • 仓库(Store)：客户端管理的一个资源库，可以向仓库中新增资源或者删除资源，或者从仓库中获取资源；
  • 控制器(Controller)：可以执行一个方法，支持参数输入，结果返回。

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 ： 通过缓存机制提升接口响应性能