REST API概述与设计规范

2022-09-17 00:04:39 阅读：375 来源： 互联网

一、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中的几个重要概念

资源（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动词

资源的原型

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

标签：HTTP,URI,REST,API,设计规范,资源,客户端
来源： https://www.cnblogs.com/lht333/p/16701682.html

本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；
2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；
3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；
4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；
5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

ICode9