RESTful API总结

一、REST介绍

概念
REST（英文：Representational State Transfer，简称REST，直译过来表现层状态转换）是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

需要注意的是REST并没有一个明确的标准，而更像是一种设计的风格，满足这种设计风格的程序或接口我们称之为RESTful(从单词字面来看就是一个形容词)。

所以RESTful API 就是满足REST架构风格的接口。

二、RESTful API设计规范

1、 URL设计规范

URL为统一资源定位器 ,接口属于服务端资源，首先要通过URL这个定位到资源才能去访问，而通常一个完整的URL组成由以下几个部分构成：

URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ] 

• scheme: 指底层用的协议，如http、https、ftp
  host: 服务器的IP地址或者域名, 如：本地（localhost）
  port: 端口，http默认为80端口
  path: 访问资源的路径，就是各web 框架中定义的route路由
  query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
  fragment: 锚点，定位到页面的资源

我们在设计API时URL的path是需要认真考虑的，而RESTful对path的设计做了一些规范，通常一个RESTful API的path组成如下：

/{version}/{resources}/{resource_id} 

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。

resources：资源，RESTful API推荐用小写英文单词的复数形式。

resource_id：资源的id，访问或操作该资源。
当然，有时候可能资源级别较大，其下还可细分很多子资源也可以灵活设计URL的path，例如：

/{version}/{resources}/{resource_id}/{subresources}/{subresource_id} 

此外，有时可能增删改查无法满足业务要求，可以在URL末尾加上action，例如

/{version}/{resources}/{resource_id}/action 

其中action就是对资源的操作。

从大体样式了解URL路径组成之后，对于RESTful API的URL具体设计的规范如下：
1、不用大写字母，所有单词使用英文且小写。
2、连字符用中杠"-“而不用下杠”_"
3、正确使用 “/“表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
4、结尾不要包含正斜杠分隔符”/”
5、URL中不出现动词，用请求方式表示动作
6、资源表示用复数不要用单数
7、不要使用文件扩展名

2、HTTP动词

在RESTful API中，不同的HTTP请求方法有各自的含义，这里就展示GET,POST,PUT,DELETE几种请求API的设计与含义分析。针对不同操作，具体的含义如下：

GET /collection：从服务器查询资源的列表（数组）  
GET /collection/resource：从服务器查询单个资源  
POST /collection：在服务器创建新的资源  
PUT /collection/resource：更新服务器资源  
DELETE /collection/resource：从服务器删除资源 

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

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

3、状态码和返回数据

服务端处理完成后客户端也可能不知道具体成功了还是失败了，服务器响应时，包含状态码和返回数据两个部分。

状态码

我们首先要正确使用各类状态码来表示该请求的处理执行结果。状态码主要分为五大类：

1xx：相关信息

2xx：操作成功

3xx：重定向

4xx：客户端错误

5xx：服务器错误

每一大类有若干小类，状态码的种类比较多，而主要常用状态码罗列在下面：

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。

202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）

204 NO CONTENT - [DELETE]：用户删除数据成功。

400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。

403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。

404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。

500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果

针对不同操作，服务器向用户返回数据，而各个团队或公司封装的返回实体类也不同，但都返回JSON格式数据给客户端。

Demo

package com.restfuldemo.controller;  
import com.restfuldemo.mapper.DogMapper;  
import com.restfuldemo.pojo.Dog;  
import org.springframework.beans.factory.annotation.Autowired;  
import org.springframework.web.bind.annotation.*;  
import java.util.Arrays;  
import java.util.List;  
@RestController  
public class TestController {  
    @Autowired(required = false)  
    DogMapper dogMapper;  
    @GetMapping("dogs")  
    public List<Dog> getDogs()  
    {  
        return  dogMapper.getAllDog();  
    }  
    @GetMapping("dogs/{id}")  
    public Dog getDogById(@PathVariable("id") int id)  
    {  
        Dog dog=dogMapper.getDogById(id);  
        return  dog;  
    }  
    @PostMapping("dogs")  
    public boolean addDog(Dog dog)  
    {  
        return dogMapper.addDog(dog); 
    }  
    @PutMapping("dogs/{id}")  
    public boolean updateDog(@PathVariable("id")int id,@RequestParam("name")String name,@RequestParam("age")int age)  
    {  
        Dog dog=dogMapper.getDogById(id);  
        dog.setName(name);  
        dog.setAge(age);  
        return  dogMapper.updateDog(dog);  
    }  
    @DeleteMapping("dogs/{id}")  
    public boolean deleteDog(@PathVariable("id") int id)  
    {  
        return  dogMapper.deleteDogById(id);  
    }  
} 

学习资源来自： https://zhuanlan.zhihu.com/p/437803444