restful接口设计

1.RESTFUL：

是一种设计风格, 而不是一种标准, 诞生于2000年, Thomas Fielding

在论文<<架构风格与基于网络的软件架构设计>>提及到的.

指的是客户端和服务器的交互形式.在后台中体现的是接口的设计!

 

2.REST的特点：

    1. 具象的资源,也就是表现层, 比如: 客户端向服务器获取的资源(文字,图片,音频)

    2. 资源表现形式,不如: txt格式, html格式, json数据格式等,在Content-Type中指定

    3. 状态转换, 客户端和服务器交互过程中,数据的转换状态,GET获取资源,POST表示新建资源,PUT更新资源,DELETE删除资源

 

总结: 1.每种URL表示一种资源, 2.客户端和服务器之间,资源传递称为表现层3.客户端通过四个动词,对服务器资源进行操作,实现表现层的状态转换

 

3.如何使用RESTful风格的API

 

一,域名

将api部署在专用域名下面

http://api.example,com

或者将api放在主域名下

http://www.example.com/api/

 

二,版本

将api的版本号放在ulr中

http://www.example.com/app/1.0/info

http://www.example.com/app/1.2/info

 

三,路径:

路径表示的是api的具体地址,每个地址表示的是一种资源,资源作为网址,不能有动词,只能用名字表示,一般名词要与数据库的表名相对应,而且名词要使用复数形式.

127.0.0.1/sms_code

错误展示:

http://www.example.com/getGoods

http://www.example.com/listOrders

 

正确示例:

获取单个商品

http://www.example.com/app/goods/1
获取所有商品

http://www.example.com/app/goods

 

四,使用标准的HTTP方法:

对于资源的具体类型的操作,由HTTP动词表示, 常用的HTTP动词有四个

GET	SELECT	从服务器获取资源
POST	CREATE	在服务器创建资源
PUT	UPDATE	在服务器更新资源
DELETE	DELETE	从服务器删除资源

 

示例:

获取指定的商品信息

GET 指定商品信息	http://www.example.com/goods/ID
POST 创建商品信息	http://www.example.com/goods
PUT 更新指定商品信息	http://www.example.com/goods/ID
DELETE 删除指定商品信息	http://www.example.com/goods/ID

 

五,过滤信息

如果资源数据较多, 服务器不能将所有的数据一次全部返回给客户端,API应该

提供参数,过滤返回结果,丧礼:

指定返回数据的数量

http://www.example.com/goods?limit=10

指定返回数据的开始位置

http://www.example.com/goods?offset=10

指定第几页,以及每页数据的数量

http://www.example.com/goods?page=2&per_age=20

 

六, 状态码

服务器向用户返回的状态码和提示信息,常用的有:

200	OK	服务器成功返回用户请求的数据
201	CREATED	用户新建或者修改数据成功
202	ACCEPTED	表示请求已经进入后台排队
400	INVALID REQUEST	用户发出的请求错误
401	Unauthorized	用户没有权限
403	Forbidden	访问被禁止
404	NOT FOUND	请求针对的是不存在的记录
406	Not Acceptable	用户请求的格式不正确
500	interal server error	服务器发生错误

 

七,错误信息

一般来说,服务器返回的错误信息,以键值对的形式返回

{error:"Invalid API KEY"}

 

八,响应结果

针对不同结果, 服务器向客户端返回的结果应符合以下规范

返回商品列表

GET http://www.example.com/goods

返回单个商品

GET http://www.example.com/goods/cup

返回新生成的商品

POST http://www.example.com/goods

返回一个空文档

DELETE http://www.example.com/goods

 

九,使用连接关联的资源

在返回响应结果是提供API方法, 是客户端很方便的获取相关的信息

 

十,其他:

服务器返回的数据格式, 应该尽量使用JSON, 避免使用XML格式