[API接口设计] RESTful 规范

RESTful是目前最流行的API设计规范，它是用于Web数据接口的设计；REST它是 Representational State Transfer的简称，中文的含义是: "表征状态转移" 或 "表现层状态转化"

1 发展来源和必要性

        RESTful API 设计由 Roy Fielding 博士在其 2000 年的博士论文中定义。后来经过社区以及互联网发展的趋势需要就慢慢成为了一个标准；

        目前我们实现一个RESTful接口，可以在web端 pc端及移动端，实现多端同时调用，而且前后端分离，使得前端开发无须关注过多后端业务逻辑；这是我们目前想当然的一个使用；其实在之前我们的页面、数据以及模板渲染工作都是在服务端进行的；也就是说以前开发者都是全栈开发；像我们上学时的.net Form等.net框架、flex开发；都是服务器端渲染，一个人进行前端页面以及后台数据查询、数据和页面模板绑定工作，一人负责多项工作；

        维护工作比较困难；这里可能更应该强调是目前这个互联网环境下 换人的成本太大；

所以这里所说的维护并不是人员的维护系统难度大小，更可能是如果一个这样的系统直接换人去维护的难度和成本大小，因为需要找一个对前端、服务端、数据查询等都需满足的人，这对于咱目前各大企业如此频繁的人员流动的市场简直就是噩梦，从这个角度来看，前后端分离势在必行，可能不仅仅是因为技术原因，市场才是主要导向吧；

所以伴随着前后端分离潮流，RESTful api标准就慢慢流行起来了；

2 Rest设计原则

后端实现的接口怎么才能算是一个rest风格的接口呢，需要满足以下风格

2.1  每一个URI代表一种资源

        这个很好理解，就是一个URI只代表一种类型的资源

http://xxx.com/api/users;        // 获取所有用户信息
http://xxx.com/api/teachers;     // 获取所有老师信息
http://xxx.com/api/areas;        // 获取所有区域信息

2.2 同一种资源有多种表现形式(xml/json)

        一种资源可以用多种格式返回，客户端请求的时候，我们可以在请求头中设置参数，要求restful返回指定类型的数据，这是RESTful接口需要满足的元原则；比如

Accept:application/xml  

请求时设置返回形式是xml，如使用ajax请求，则需要设置contentType:application/xml

Accept:application/json  

请求时设置返回形式是json，如使用ajax请求，则需要设置contentType:application/json

2.3 所有的操作都是无状态的

        http请求本身是无状态的，而RESTful是建立在无状态http协议基础上的；所以本身RESTful的各种请求也是无状态的；

        怎么理解这个无状态呢

        可以这么理解:协议对于事务处理没有记忆能力。缺少状态意味着如果后续处理需要前面的信息，则它必须重传，这样可能导致每次连接传送的数据量增大。但另一方面，在服务器不需要先前信息时它的应答就较快。

        举个，当浏览器发送请求给服务器的时候，服务器响应，但是同一个浏览器再发送请求给服务器的时候，他会响应，但是他不知道你就是刚才那个浏览器，简单地说，就是服务器不会去记得你；

所以如果需要有状态之类的记忆功能，就借助浏览器的cookie、session及token技术去实现即可；

2.4 规范统一接口

Rest接口约束定义为:

资源识别：它表示通过uri表示出要操作的资源；

请求动作：通过请求动作(http method)标识要执行的操作；

响应信息;：通过返回的状态码来表示这次请求的执行结果；

直接对比下

达不到RESTful接口规范的普通接口：

http://xxx.com/api/getallUsers; // GET请求方式，获取所有的用户信息
http://xxx.com/api/getuser/1;   // GET请求方式，获取标识为1的用户信息
http://xxx.com/api/user/delete/1 // GET、POST 删除标识为1的用户信息
http://xxx.com/api/updateUser/1  // POST请求方式 更新标识为1的用户信息
http://xxx.com/api/User/add      // POST请求方式，添加新的用户

标准统一的RESTful风格接口规范： 

http://xxx.com/api/users;     // GET请求方式 获取所有用户信息
http://xxx.com/api/users/1;   // GET请求方式 获取标识为1的用户信息
http://xxx.com/api/users/1;   // DELETE请求方式 删除标识为1的用户信息
http://xxx.com/api/users/1;   // PATCH请求方式，更新标识为1的用户部分信息
http://xxx.com/api/users;     // POST请求方式 添加新的用户

2.5 返回一致的数据格式

这个也好理解，比如返回的数据格式，最起码有我们标准要求的几个字段，比如状态、code、信息、data等。如下

{
    "code": 401,
    "status": "error",
    "message": '用户没有权限',
    "data": null
}

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "小白GIS",
        "age": 7
    }]
}

2.6 可缓存(客户端可以缓存响应的内容)

        现在接口基本都提供了可缓存的功能，也就是说在接口开发阶段，我们会设置浏览器是否可以缓存，以及缓存的类型和有效时间等等.比如强缓存、协商缓存规范都是服务器端设置的

3 RESTful接口规范

3.1 uri规范

我们在接口路径定义的时候，尽量使用如下规范即可

1) uri末尾不需要出现斜杠/
2) 在uri中使用斜杠/是表达层级关系的。
3) 在uri中可以使用连接符-, 来提升可读性。
比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可读性更好。
4) 在uri中不允许出现下划线字符_.
5) 在uri中尽量使用小写字符。
6) 在uri中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。
7) 在uri中使用复数形式。

        注意:在RESTful架构中，每个uri代表一种资源，因此uri设计中不能使用动词，只能使用名词，并且名词中也应该尽量使用复数形式。使用者应该使用相应的http动词 GET、POST、PUT、PATCH、DELETE等操作这些资源即可。

3.2 请求方式

GET (SELECT): 查询；从服务器取出资源.
POST(CREATE): 新增; 在服务器上新建一个资源。
PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE): 更新；在服务器上更新部分资源(客户端提供改变的属性)。
DELETE(DELETE): 删除; 从服务器上删除资源。

3.3 参数命名规范

参数建议使用下划线 

http://xxx.com/api/male_users // 获取男性用户。
http://xxx.com/api/male_users&sort=age_desc // 获取年纪降序的男性用户

4 状态码 

分类	分类描述
1**	信息，服务器收到请求，需要请求者继续执行操作
2**	成功，操作被成功接收并处理
3**	重定向，需要进一步的操作以完成请求
4**	客户端错误，请求包含语法错误或无法完成请求
5**	服务器错误，服务器在处理请求的过程中发生了错误

状态码	状态码英文名称	中文描述
100	Continue	继续。客户端应继续其请求
101	Switching Protocols	切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到HTTP的新版本协议
200	OK	请求成功。一般用于GET与POST请求
201	Created	已创建。成功请求并创建了新的资源
202	Accepted	已接受。已经接受请求，但未处理完成
203	Non-Authoritative Information	非授权信息。请求成功。但返回的meta信息不在原始的服务器，而是一个副本
204	No Content	无内容。服务器成功处理，但未返回内容。在未更新网页的情况下，可确保浏览器继续显示当前文档
205	Reset Content	重置内容。服务器处理成功，用户终端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域
206	Partial Content	部分内容。服务器成功处理了部分GET请求
300	Multiple Choices	多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择
301	Moved Permanently	永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替
302	Found	临时移动。与301类似。但资源只是临时被移动。客户端应继续使用原有URI
303	See Other	查看其它地址。与301类似。使用GET和POST请求查看
304	Not Modified	未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源
305	Use Proxy	使用代理。所请求的资源必须通过代理访问
306	Unused	已经被废弃的HTTP状态码
307	Temporary Redirect	临时重定向。与302类似。使用GET请求重定向
400	Bad Request	客户端请求的语法错误，服务器无法理解
401	Unauthorized	请求要求用户的身份认证
402	Payment Required	保留，将来使用
403	Forbidden	服务器理解请求客户端的请求，但是拒绝执行此请求
404	Not Found	服务器无法根据客户端的请求找到资源（网页）。通过此代码，网站设计人员可设置"您所请求的资源无法找到"的个性页面
405	Method Not Allowed	客户端请求中的方法被禁止
406	Not Acceptable	服务器无法根据客户端请求的内容特性完成请求
407	Proxy Authentication Required	请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权
408	Request Time-out	服务器等待客户端发送的请求时间过长，超时
409	Conflict	服务器完成客户端的 PUT 请求时可能返回此代码，服务器处理请求时发生了冲突
410	Gone	客户端请求的资源已经不存在。410不同于404，如果资源以前有现在被永久删除了可使用410代码，网站设计人员可通过301代码指定资源的新位置
411	Length Required	服务器无法处理客户端发送的不带Content-Length的请求信息
412	Precondition Failed	客户端请求信息的先决条件错误
413	Request Entity Too Large	由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息
414	Request-URI Too Large	请求的URI过长（URI通常为网址），服务器无法处理
415	Unsupported Media Type	服务器无法处理请求附带的媒体格式
416	Requested range not satisfiable	客户端请求的范围无效
417	Expectation Failed	服务器无法满足Expect的请求头信息
500	Internal Server Error	服务器内部错误，无法完成请求
501	Not Implemented	服务器不支持请求的功能，无法完成请求
502	Bad Gateway	作为网关或者代理工作的服务器尝试执行请求时，从远程服务器接收到了一个无效的响应
503	Service Unavailable	由于超载或系统维护，服务器暂时的无法处理客户端的请求。延时的长度可包含在服务器的Retry-After头信息中
504	Gateway Time-out	充当网关或代理的服务器，未及时从远端服务器获取请求
505	HTTP Version not supported	服务器不支持请求的HTTP协议的版本，无法完成处理

以上就是RESTful API规范了；只要咱的接口能满足以上规范和设计原则；就是一个RESTful 接口