分享知识 传递快乐
1、什么是RESTful
1）REST与技术无关，代表的是一种软件架构风格（REST是Representational State Transfer的简称，中文翻译为“表征状态转移”）
2）REST从资源的角度类审视整个网络，它将分布在网络中某个节点的资源通过URL进行标识
3）所有的数据，不过是通过网络获取的还是操作（增删改查）的数据，都是资源，将一切数据视为资源是REST区别与其他架构风格的最本质属性
4）对于REST这种面向资源的架构风格，有人提出一种全新的结构理念，即：面向资源架构（ROA：Resource Oriented Architecture）
2、了解什么是API
什么是API？
API就是接口，提供的url。接口有两个用途：
- 为别人提供服务
- 前后端分离，一个写vue，一个写后端，他们之间都是通过ajax请求
3、主要的设计原则
- 资源与URI
- 统一资源接口(HTTP方法如GET，PUT和POST)
- 资源的表述
- 资源的链接
- 状态的转移
4、RESTful API设计规范
1）使用协议
API与用户的通信协议，总是使用HTTPS协议。
2）域名
有两种方式
方式一： 尽量将API部署在专用域名（会存在跨域问题）
https://api.example.com
方式二：如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
https://example.org/api/
3）版本
API版本一般放在URL中，简洁明了，例：
https://api.example.com/v1/
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。
4）参数命名规范
可以采用驼峰命名法，也可以采用下划线命名的方式，推荐采用下划线命名的方式，使用采用下划线的的方式识别度更高。
5）URL命名规范
API 命名为保持简洁明了，应该采用约定俗成的方式。在RESTful架构中，每个URL代表一种资源，所以URL中均使用名词表示（可复数）。
下面参考一下规范的URL和不规范的URL做个对比：
不规范的的url，形式不固定，可读性不强，增加维护和阅读成本，不同的开发者需要了解文档才能调用。
https://www.api.com/api/getallUsers GET 获取所有用户
https://www.api.com/api/getuser/1 GET 获取标识为1用户信息
https://www.api.com/api/user/delete/1 GET/POST 删除标识为1用户信息
https://www.api.com/api/updateUser/1 POST 更新标识为1用户信息
https://www.api.com/api/User/add POST 添加新的用户
规范后的RESTful风格的url，形式固定，可读性强，根据名词就可以清楚的知道在操作哪些资源。
https://www.api.com/api/users GET 获取所有用户信息
https://www.api.com/api/users/1 GET 获取标识为1用户信息
https://www.api.com/api/users/1 DELETE 删除标识为1用户信息
https://www.api.com/api/users/1 Patch 更新标识为1用户部分信息,包含在body中
https://www.api.com/api/users POST 添加新的用户
6）HTTP动词
对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个（括号里是对应的SQL命令）。了解常见HTTP请求方法。
GET（SELECT）：从服务器取出资源（一项或多项）。即获取数据
POST（CREATE）：在服务器新建一个资源。 即添加数据
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。即更新数据
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。即更新数据
DELETE（DELETE）：从服务器删除资源 。即删除数据
下面是一些例子：
GET /users：列出所有用户
POST /users：新建一个用户
GET /users/ID：获取某个指定用户的信息
PUT /users/ID：更新某个指定用户的信息（提供该用户的全部信息）
PATCH /users/ID：更新某个指定用户的信息（提供该用户的部分信息）
DELETE /users/ID：删除某个用户
GET /users/ID/infos：列出某个指定用户的所有信息
DELETE /users/ID/infos/ID：删除某个指定用户的指定信息
7）过滤信息
https://www.api.com/v1/users?limit=10：指定返回记录的数量
https://www.api.com/v1/users?offset=10：指定返回记录的开始位置
https://www.api.com/v1/users?page=2&per_page=100：指定第几页，以及每页的记录数
https://www.api.com/v1/users?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序
https://www.api.com/v1/users?animal_type_id=1：指定筛选条件
8）返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范：
GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档
统一返回数据格式
对于合法的请求应该统一返回数据格式，这里只说明一下JSON的方式：
- code：包含一个整数类型的HTTP响应状态码。
- status：包含文本：”success”，”fail”或”error”。
- message：当状态值为”fail”和”error”时有效，用于显示错误信息。参照国际化（il8n）标准，它可以包含信息号或者编码，可以只包含其中一个，或者同时包含并用分隔符隔开。
- data：包含响应的body。当状态值为”fail”或”error”时，data仅包含错误原因或异常名称、或者null也是可以的返回成功的响应json格式
返回成功的响应
{
"code": 200,
"message": "success",
"data": {
"userName": "abc",
"age": 16,
"address": "cn"
}
}
返回失败的响应
{
"code": 401,
"message": "error",
"data": null
}
9）Hypermedia API 超媒体API
RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。
{"link": {
"rel": "collection https://www.example.com/zoos", #表示这个API与当前网址的关系
"href": "https://api.example.com/zoos", #API路径
"title": "List of zoos", #API的标题
"type": "application/vnd.yourformat+json" #返回类型
}}
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。
{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}
提示：从个从研发习惯比较喜欢服务间访问用XML报文请求和响应，但响应页面或ajax时用JSON报文。在后期文章中会介绍到。
———————————
相互学习，共同进步
如有不足请留言指正
