restful风格接口 restful api接口风格

转载

mob64ca141677f9 2024-04-17 12:59:57

文章标签 restful风格接口 API RESTFul 字段 REST 文章分类 云原生云计算

一、什么是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 相关注意事项

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

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了。