RESTFul 风格的API

一、什么是RESTFul

RESTful是基于http方法的API设计风格而不是一种技术。可以说使用这种设计风格我们看到url就知道要什么样的资源、看到http method就知道要针对资源干什么、看到http的 status code就知道结果是什么。使用RESTFul风格的api规范了程序员的代码开发，为前后端的交互减少了接口交流的口舌成本。

二、RESTFul风格的具体体现

2.1 REST 面向资源的（名词）

REST通过URI暴露资源的时候，会强调不要再 URI 中出现的动词，比如：

不符合REST的接口的URI	符合REST接口的URI	功能
GET /api/getDog	GET /api/dogs/{id}	获取一个小狗狗对象
GET /api/getDogs	GET /api/dogs	获取所有小狗狗对象
GET /api/addDog	POST /api/dogs	添加一个小狗狗对象
GET /api/editDog/{id}	PUT /api/dogs/{id}	修改一个小狗狗对象
GET /api/deleteDog/{id}	DELETE /api/dogs/{id}	删除一个小狗狗对象

从上面的表格中我们可以看出，RESTFul风格的接口通过 URI 来暴露资源的时候里面是没有动词的

2.2. 那么问题来了，那么怎样体现对资源的操作呢

2.2.1 用HTTP方法体现对资源的操作

方法	功能
GET	获取资源
POST	添加资源
PUT	修改资源
DELETE	删除资源

2.3 HTTP状态码

通过 HTTP 状态码来体现状态的结果，结果无非是两种情况，成功、客户端错误、服务器端错误

状态码	显示的消息	表示的意义
200	OK	所有事情按照预期正确执行完毕 - 成功
400	Bad Request	API发生了一些错误 - 客户端错误
500	Internal Server Error	API 发生了一些错误 - 服务器端错误

2.4 相关注意事项

1. Get方法和查询参数不应该改变数据，改变数据的事情交给POST、PUT、DELETE
2. 使用复数名词，而不要使用单数名词
3. 复杂资源关系的表达

GET /cars/711/drivers/ 返回使用 car 711的所有司机

GET /cars/711/drivers/4 返回使用car 711的4号司机

2.6高级用法：：HATEOAS

HATEOAS 的全称为 Hypermedia as the Engine of Application State（超媒体作为应用状态的引擎），什么意思呢，就是返回结果中提供链接，连向其它API方法，使得用户不查文档也知道下一步应该做什么。

例子如下：

{
    "link":{
        "rel":"collection https://www.example.com/zoos",
        "href":"https://api.example.com/zoos",
        "title":"List of zoos",
        "type":"application/vnd.yourformat+json"
    }
}

这里表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。

2.8为集合提供过滤、排序、选择和分页等功能

Filtering过滤：

使用唯一的查询参数进行过滤：

GET /car?color=red 返回红色的cars

GET /car?seats<=2 返回小于两座位的cars集合

Sorting排序：

允许对多个字段进行排序

GET /cars?sort=-manufactor,+model

这个意思是返回根据生产者降序和模型升序排列的car集合，减号表示倒序，加号表示升序

Filed selection

移动端能够显示其中的一些字段，它们其实不需要一个资源的所有字段，给API消费者选择一个字段的能力，这样会降低网络流量，提高API的可用性。

GET /cars?fileds=manufactor,model,id,color

Paging分页

使用 limit 和 offfset ，实现分页，缺省limit=20 和offset =0:

/cars?offset=10&limit=5

2.9版本化你的API

使得API版本变得强制性，不要发布无版本的API。

/api/v1/blog 面向扩展开放，面向修改关闭，在这里v1就是指的版本

注：上述笔记来自于笔者平时看视频整理所得，如有侵权还请联系删除