RestfulAPI的接⼝规范
发展背景及简介
⽹络应⽤程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（⼿机、平板、桌⾯电脑、其他专⽤设备…）。因此，必须有⼀种统⼀的机制，⽅便不同的前端设备与后端进⾏通信。这导致API构架的流⾏，RESTful API是⽬前⽐较成熟的⼀套互联⽹应⽤程序的API设计理论。
rest是Representational State Transfer三个单词的缩写，由Roy Fielding于2000年论⽂中提出的⼀种web软件结构风格，注意它仅仅只是代表着⼀种风格，并不代表着约束、标准。基于REST构建的API就是Restful风格。 如果⼀个架构符合REST的约束条件和原则，我们就称它为RESTful架构。REST本⾝并没有创造新的技术、组件或服务，⽽隐藏在RESTful背后的理念就是使⽤Web的现有特征和能⼒， 更好地使⽤现有Web标准中的⼀些准则和约束。虽然REST本⾝受Web技术的影响很深， 但是理论上REST架构风格并不是绑定在HTTP上，只不过⽬前HTTP是唯⼀与REST相关的实例。
以webServer来解释:
⾮Rest设计，以往我们都会这么写：
总结：以不同的URL（主要为使⽤动词）进⾏不同的操作
Rest架构：
总结：URL只指定资源，以HTTP⽅法动词进⾏不同的操作,⽤HTTP STATUS/CODE定义操作结果。
Restful：遵守了rest风格的web服务便可称为Restful结构.
REST架构风格的设计原则
客户端-服务器（Client-Server）
客户端-服务器结构限制的⽬的是将客户端和服务器端的关注点分离。将⽤户界⾯数据存储所关注的逻辑分离开来有助于提⾼⽤户界⾯的跨平台的可移植性，通过简化服务器模块也有助于服务器模块的可扩展性
⽆状态（Stateless）
服务器不能保存客户端的信息每⼀次从客户端发送的请求中, 要包含所有的状态信息, 会话信息由客户端保存, 服务器端根据这些状态信息来处理请求。服务器可以将会话状态信息传递给其他服务, ⽐如数据库服务, 这样可以保持⼀段时间的状态信息, 从⽽实现认证功能。
当客户端可以切换到⼀个新状态的时候发送请求信息。当⼀个或者多个请求被发送之后, 客户端就处于⼀个状态变迁过程中。 每⼀个应⽤的状态描述可以被客户端⽤来初始化下⼀次的状态变迁
缓存（Cacheability）
如同万维⽹⼀样, 客户端和中间的通讯传递者可以将回复缓存起来。回复必须明确的或者间接的表明本⾝是否可以进⾏缓存, 这可以预防客户端在将来进⾏请求的时候得到陈旧的或不恰当的数据。管理良好的缓存机制可以减少客户端-服务器之间的交互, 甚⾄完全避免客户端-服务器交互, 这进⼀步提了⾼性能和可扩展性
统⼀接⼝（Uniform Interface）
这是 RESTful 系统设计的基本出发点。它简化了系统架构, 减少了耦合性, 可以让所有模块各⾃独⽴的进⾏改进各⾃独⽴的进⾏改进
Restful API架构风格中请求规范规范
⼀、http状态码：
使⽤http状态码定义api执⾏结果，http 定义了⼀系列可以⽤在接⼝返回的有含义的状态码。下⾯是常⽤状态码解释：
⼆、路径规范：01 分隔符/"分隔符⼀般⽤来对资源层级的划分，例如 classes
对于REST API来说，"/"只是⼀个分隔符，并⽆其他含义。为了避免混淆，"/"不应该出现在URL的末尾。例如以下两个地址实际表⽰的都是同⼀个资源：classes/classes
REST API对URI资源的定义具有唯⼀性，⼀个资源对应⼀个唯⼀的地址。为了使接⼝保持清晰⼲净，如果访问到末尾包含 "/" 的地
址，服务端应该301到没有 "/"的地址上。当然这个规则也仅限于REST API接⼝的访问，对于传统的WEB页⾯服务来说，并不⼀定适⽤这个规则
02 路径中使⽤连字符 -代替下划线 _
连字符"-"⼀般⽤来分割URI中出现的字符串(单词)，来提⾼URI的可读性，例如：
class/{class_id}/reading-corner百度api接口
使⽤下划线"_"来分割字符串(单词)可能会和链接的样式冲突重叠，⽽影响阅读性。但实际上，"-"和"_"对URL中字符串的分割语意上还是有些差异的："-"分割的字符串(单词)⼀般各⾃都具有独⽴的含义，可参见上⾯的例⼦。⽽"_"⼀般⽤于对⼀个整体含义的字符串做了层级的分割，⽅便阅读，例如你想在URL中体现⼀个ip地址的信息：210_110_25_88
对于参数名称，使⽤下划线进⾏连接，⽐如 app_id
03 路径中统⼀使⽤⼩写字母
根据RFC3986定义，URI是对⼤⼩写敏感的，所以为了避免歧义，我们尽量⽤⼩写字符。但主机名(Host)和scheme（协议名称:http/ftp/…）对⼤⼩写是不敏感的
三、请求⽅式
http method对应不同的请求动作
总 结Restful API的接⼝架构风格中制定了⼀些规范，极⼤的简化了前后端对接的时间，以及增加了开发效率，在实际开发中，⽐如在获取列表分页的时候，对于查询参数过多的接⼝，会导致uri的长度过长、请求失败，在这种情况下的接⼝就不能完全按照Restful API的请求规范来。Restful API也就只是⼀种接⼝架构的风格，接⼝API永远不会强约束于此，因按照实际需求做出相应的接⼝需改。
参考:

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。