RestFul风格简介和规范-JZTXT

Rest架构风格的设计原则

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

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

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

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

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

Restful API 架构风格中请求规范

一、 Http状态码

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

分类:

1xx: 信息，请求收到了，继续处理
2xx: 代表成功. 行为被成功地接收、理解及采纳
3xx: 重定向
4xx: 客户端错误，请求包含语法错误或请求无法实现
5xx: 服务器端错误

状态码	含义
200	OK [GET]: 服务器端成功返回用户请求的数据
201	CREATED [POST/PUT/PATCH]: 用户新建或修改数据成功
202	Accepted 表示一个请求已经进入后台排队(一般是异步任务)
204	NO CONTENT -[DELETE]: 用户删除数据成功
400	Bad Request - [POST/PUT/PATCH]: 用户发出的请求有错误，服务器不理解客户端的请求，未做任何处理
401	Unauthorized; 表示用户没有权限(令牌、用户名、密码错误)
403	Forbidden: 表示用户得到授权了，但是访问被禁止了, 也可以理解为不具有访问资源的权限
404	Not Found: 所请求的资源不存在，或不可用
405	Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内
406	Not Acceptable: 用户的请求的格式不可得(比如用户请求的是JSON格式，但是只有XML格式)
410	Gone - [GET]: 用户请求的资源被转移或被删除。且不会再得到的
415	Unsupported Media Type: 客户端要求的返回格式不支持，比如，API只能返回JSON格式，但是客户端要求返回XML格式
422	Unprocessable Entity: 客户端上传的附件无法处理，导致请求失败
429	Too Many Requests: 客户端的请求次数超过限额
500	INTERNAL SERVER ERROR; 服务器发生错误
502	网关错误
503	Service Unavailable 服务器端当前无法处理请求
504	网关超时

二、路径规范

分隔符

分隔符一般用来对资源层级的划分

对于REST API来说，"/"只是一个分隔符，并无其他含义。为了避免混淆，"/"不应该出现在URL的末尾

REST API对URI资源的定义具有唯一性，一个资源对应一个唯一的地址。为了使接口保持清晰干净，如果访问到末尾包含 "/" 的地址，服务端应该301到没有 "/"的地址上。当然这个规则也仅限于REST API接口的访问，对于传统的WEB页面服务来说，并不一定适用这个规则
路径中使用连字符 -代替下划线 _

连字符"-"一般用来分割URI中出现的字符串(单词)，来提高URI的可读性.

使用下划线""来分割字符串(单词)可能会和链接的样式冲突重叠，而影响阅读性。但实际上，"-"和""对URL中字符串的分割语意上还是有些差异的："-"分割的字符串(单词)一般各自都具有独立的含义。而"_"一般用于对一个整体含义的字符串做了层级的分割，方便阅读，例如你想在URL中体现一个ip地址的信息：210_110_25_88

对于参数名称，使用下划线进行连接，比如 app_id
路径中统一使用小写字母

根据RFC3986定义，URI是对大小写敏感的，所以为了避免歧义，我们尽量用小写字符。但主机名(Host)和scheme（协议名称:http/ftp/…）对大小写是不敏感的