分享知识 传递快乐
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报文。在后期文章中会介绍到。
———————————
相互学习,共同进步
如有不足请留言指正