Restful API 的接口规范

发展背景及简介
网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致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设计，以往我们都会这么写：

http://xxx.com:8080/posts/getAtricle (查询文章)

http://xxx.com:8080/posts/addAtricle (新增文章)

http://xxx.com:8080/posts/updateAtricle (更新文章)

http://xxx.com:8080/posts/deleteAtricle (删除文章)

总结：以不同的URL（主要为使用动词）进行不同的操作

Rest架构：

GET http://xxx.com:8080/posts/atricle（查询文章）

POST http://xxx.com:8080/posts/atricle（新增文章）

PUT http://xxx.com:8080/posts/atricle（新增文章）

DELETE http://xxx.com:8080/posts/atricle（删除文章）

总结：URL只指定资源，以HTTP方法动词进行不同的操作,用HTTP STATUS/CODE定义操作结果。

Restful：遵守了rest风格的web服务便可称为Restful结构.

REST架构风格的设计原则

客户端-服务器（Client-Server）

客户端-服务器结构限制的目的是将客户端和服务器端的关注点分离。将用户界面数据存储所关注的逻辑分离开来有助于提高用户界面的跨平台的可移植性，通过简化服务器模块也有助于服务器模块的可扩展性

无状态（Stateless）

服务器不能保存客户端的信息每一次从客户端发送的请求中, 要包含所有的状态信息, 会话信息由客户端保存, 服务器端根据这些状态信息来处理请求。服务器可以将会话状态信息传递给其他服务, 比如数据库服务, 这样可以保持一段时间的状态信息, 从而实现认证功能。当客户端可以切换到一个新状态的时候发送请求信息。当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁

缓存（Cacheability）

如同万维网一样, 客户端和中间的通讯传递者可以将回复缓存起来。回复必须明确的或者间接的表明本身是否可以进行缓存, 这可以预防客户端在将来进行请求的时候得到陈旧的或不恰当的数据。管理良好的缓存机制可以减少客户端-服务器之间的交互, 甚至完全避免客户端-服务器交互, 这进一步提了高性能和可扩展性

统一接口（Uniform Interface）

这是 RESTful 系统设计的基本出发点。它简化了系统架构, 减少了耦合性, 可以让所有模块各自独立的进行改进各自独立的进行改进

Restful API架构风格中请求规范规范

一、http状态码：

使用http状态码定义api执行结果，http 定义了一系列可以用在接口返回的有含义的状态码。下面是常用状态码解释：

二、路径规范：

01 分隔符

/"分隔符一般用来对资源层级的划分，例如 http://api.domain.com/school/classes
对于REST API来说，"/"只是一个分隔符，并无其他含义。为了避免混淆，"/"不应该出现在URL的末尾。例如以下两个地址实际表示的都是同一个资源：
http://api.domain.com/school/classes/
http://api.domain.com/school/classes
REST API对URI资源的定义具有唯一性，一个资源对应一个唯一的地址。为了使接口保持清晰干净，如果访问到末尾包含 "/" 的地址，服务端应该301到没有 "/"的地址上。当然这个规则也仅限于REST API接口的访问，对于传统的WEB页面服务来说，并不一定适用这个规则

02 路径中使用连字符 -代替下划线 _

连字符"-"一般用来分割URI中出现的字符串(单词)，来提高URI的可读性，例如：
http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post
http://api.domain.com/school/class/{class_id}/reading-corner
使用下划线"_"来分割字符串(单词)可能会和链接的样式冲突重叠，而影响阅读性。但实际上，"-"和"_"对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永远不会强约束于此，因按照实际需求做出相应的接口需改。

参考: 浅谈Restful API 的请求规范 - 知乎