RESTful API介绍与简单使用

什么是 RESTful API

API（应用程序接口）是一组使不同程序能够相互通信的规则。
REST 即 表述性状态传输（Representational State Transfer，REST），REST并没有一个明确的标准，而更像是一种设计的风格，满足这种设计风格的程序或接口我们称之为RESTful。而 RESTful API 就是满足REST架构风格的接口。

RESTful API 是一种遵循表述性状态传输（REST）架构原则的 API。

REST API 设计规范与实现

URL 一般由一下几部分组成：

scheme(协议:http/https)  "://" host(IP地址或为域名) ":" port(端口，不输入则默认为80) "/" path(资源路径，比如web框架中的路由地址) ["?" params (查询参数)] [fragment(页面资源)]

而 RESTful 对 API 设计做了一些规范, 一般情况下，我们的 RESTful API 的组成如下：

API URL PATH

api/{version}/{resource}/[id]

RESTful API 的设计规范如下：

设计规范

• 不用大写字母，所有单词使用英文且小写
• 连字符用中杠”-“，而不用下杠”_”
• 正确使用 “/“表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
• 结尾不要包含正斜杠分隔符”/“
• URL中不出现动词，用请求方式表示动作（到这里是否理解了表述性状态传输呢？）
• 资源表示用复数不要用单数
• 不要使用文件扩展名

tips

在非 RESTful 风格的 API 中，我们通常使用 GET 请求和 POST 请求完成增删改查以及其他操作，查询和删除一般使用 GET 方式请求，更新和插入一般使用POST请求。从请求方式上无法知道 API 具体是干嘛的，所有在 URL 上都会有操作的动词来表示API进行的动作，例如：query，add，update，delete等等。

而 RESTful 风格的 API 则要求在 URL 上都以名词的方式出现，从几种请求方式上就可以看出想要进行的操作，这点与非 RESTful 风格的 API 形成鲜明对比。

REST API 设计案例

@RequestMapping(value = "/deviceUseOperates")
public class ExampleController {


    /**
     * getList
     * GET  http://xxxx.xxx/api/v1/deviceUseOperates
     */
    @GetMapping
    public ResponseEntity<IPage<DeviceUseOperateDTO>> list(DeviceUseOperateDTO deviceUseOperateDTO, Page<DeviceUseOperateDTO> page) throws Exception {
        // list()
        return ResponseEntity.ok(null);
    }

    /**
     * queryOne
     *
     * @param id queryById
     * GET   http://xxxx.xxx/api/v1/deviceUseOperates/1008611
     * @return
     */
    @GetMapping("/{id}")
    public ResponseEntity<DeviceUseOperateDTO> queryById(@PathVariable String id) {
        // queryById()
        return ResponseEntity.ok(null);
    }

    /**
     * save
     *
     * @param deviceUseOperateDTO 
     * POST  http://xxxx.xxx/api/v1/deviceUseOperates
     * @return
     */
    @PostMapping
    public ResponseEntity<String> save(@Valid @RequestBody DeviceUseOperateDTO deviceUseOperateDTO) {
        // svae();
        return ResponseEntity.ok(null);
    }

    /**
     * update
     *
     * @param deviceUseOperateDTO 
     * PUT  http://xxxx.xxx/api/v1/deviceUseOperates
     * @return
     */
    @PutMapping
    public ResponseEntity<String> update(@Valid @RequestBody DeviceUseOperateDTO deviceUseOperateDTO) {
        // update();
        return ResponseEntity.ok(null);
    }

    /**
     * delete
     *
     * @param ids
     * DELETE ttp://xxxx.xxx/api/v1/deviceUseOperates/1008611,1008612,1008613
     * @return
     */
    @DeleteMapping("/{ids}")
    public ResponseEntity<String> delete(@PathVariable String ids) {
        // removeByIds();
        return ResponseEntity.ok(null);
    }

}

• GET
• POST
• PUT
• DELETE

• GET 请求用来获取资源：
  在本文案例中使用到了如下 GET 请求的 API
  GET http://xxxx.xxx/api/v1/deviceUseOperates ：用来返回 deviceUseOperate 资源的列表
  GET http://xxxx.xxx/api/v1/deviceUseOperates/{id} ：用来返回 deviceUseOperate 中 id = {id} 资源的列表

• POST 请求用来新增一个资源:
  在本案例中，我们设计以下 POST 请求的 API
  POST http://xxxx.xxx/api/v1/deviceUseOperates : 用于在服务端新增一个 deviceUseOperates 资源

• PUT 请求用来更新资源：
  在本案例中，我们设计以下POST请求的API
  PUT http://xxxx.xxx/api/v1/deviceUseOperates : 配合使用 @RequstBody 来更新资源，亦可根据 id 更新，如下
  PUT http://xxxx.xxx/api/v1/deviceUseOperates/{id} : 用于更新单个 id = {id} 的资源

• DELETE 请求用来删除资源：
  在本案例中，我们设计以下DELETE请求的API
  DELETE http://xxxx.xxx/api/v1/deviceUseOperates/{idS} : 用于删除此id(ids)的单(多)个 deviceUseOperates 资源

总结

RESTful API是一种风格，而不是一种约束或强制规范，建议借鉴为主，取其精华去其糟粕。

简单粗暴的总结一下：

- GET 查询
- POST 新增
- PUT 修改
- DELETE 删除 

好的，”无用”的冷知识又 GET 了！