RESTful API 原理及示例

RESTful用来干什么

• RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计

RESTful架构的主要原则

• REST是英文representational state transfer(表象性状态转变)或者表述性状态转移;Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计;它是一种设计风格,不是一种标准,是一种思想
• Rest架构的主要原则 网络上的所有事物都被抽象为资源
  每个资源都有一个唯一的资源标识符
  同一个资源具有多种表现形式(xml,json等)
  对资源的各种操作不会改变资源标识符
  所有的操作都是无状态的
  符合REST原则的架构方式即可称为RESTful
• 什么是Restful?
  对应的中文是rest式的;Restful web service是一种常见的rest的应用,是遵守了rest风格的web服务;rest式的web服务是一种ROA(TheResource-Oriented-Architecture)(面向资源的架构).

为什么会出现Restful

在Restful之前的操作：

http://localhost/user/query/1 GET 查
http://localhost/user/save POST 增
http://localhost/user/update POST 改
http://localhost/user/delete GET/POST 删

RESTful用法：

http://localhost/user/1 GET 查
http://localhost/user POST 增
http://localhost/user PUT 改
http://localhost/user/1 DELETE 删

为什么要使用RESTful

之前的操作其实是没有问题的,大神认为是有问题的,有什么问题呢?你每次请求的接口或者地址,都在做描述,例如查询的时候用了query,新增的时候用了save,其实完全没有这个必要,我使用了get请求,就是查询.使用post请求,就是新增的请求,我的意图很明显,完全没有必要做描述,这就是为什么有了restful
RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语,而且宾语必须是名词，比如/user这个url就是正确的，而/getUser这个就是错误的，因为它不是名词

一般我们在使用restful的接口时，会使用到swagger2，以下是swagger2的注解说明，方便我们学习

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
    
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
    
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性