Restful API

是一种互联网软件架构设计规范、设计指南、设计风格、设计原则。

定义

API： 应用程序接口（接口）。

Rest： Resource Representational State Transfer。

• Resource 资源

URI：统一资源标识符。是一个字符串。用来标识互联网资源的名称。 资源定义的地址。

URL：统一资源定位符，他是具体的URI。好比构造函数生成的实例。儿子。地址的具体表现。

• Representational 表现层

资源的表现形式：content-type。

比如： 文本  text\html\xml\json\二进制

• State Transfer 状态转化

Restful API 具体设计规范

1. 协议

HTTPS

2. 域名

api.kaivon.com

api.kaivon.com/api/

3. 版本

api.kaivon.com/v1

4. 路径

资源的地址。

要求：路径不能有动词，只能是名词。所用名词要和数据库表名相对应。因为数据库表内数据很多，一般用表名的复数。

// (blog是表名）
https://api.kaivon.com/v1/blogs 

5. 方法

• GET 获取资源

GET https://api.kaivon.com/v1/blogs 获取所有的文章
GET https://api.kaivon.com/v1/blogs/id 获取某一篇文章

• POST 添加资源

POST https://api.kaivon.com/v1/blogs 增加一篇文章

• PUT 修改资源

PUT https://api.kaivon.com/v1/blogs/id 修改某一篇文章

• PATCH 更新资源

PATCH https://api.kaivon.com/v1/blogs/id 更新某一篇文章

• DELETE 删除资源

DELETE https://api.kaivon.com/v1/blogs/id 删除某一篇文章

6. 数据过滤

• ?limit=10 指定返回数据的数量

GET https://api.kaivon.com/v1/blogs?limit=10

• ?offset=10 指定一个偏移量

GET https://api.kaivon.com/v1/blogs?offset=10

• ?page=2&per_page=10 指定第几页，以及每页的数量

GET https://api.kaivon.com/v1/blogs?page=2&per_page=10

• ?sortby=time&order=arc 指定返回结果按照哪个属性排序，以及排序的顺序

GET https://api.kaivon.com/v1/blogssortby=time&order=arc

7. 状态码

8. 返回结果

• GET

资源对象列表（数组），如果取的是一条数据,那返回一个对象

• POST

返回添加后的资源对象，以及有可能会加上是否成功

• PUT

返回修改后的资源对象，以及有可能会加上是否成功

• PATCH

返回更新后的资源对象，以及有可能会加上是否成功

• DELETE

返回空，以及有可能会返回是否成功

9. 返回的数据格式

尽量使用json，避免使用XML。