什么是RESETful API架构
一、什么是RESTful API架构？
REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的。他对互联网软件的架构原则，定名为REST，即Representational State Transfer的缩写。阮一峰博主将其翻译为"表现层状态转化"。如果一个架构符合REST原则，就称它为RESTful架构。只要理解了Representational State Transfer各个单词的含义，基本上就了解了REST的定义。
1、表现层（Representation）
表现层（Representation）是资源（Resources）的外在表现形式。网络上的一段文本、一张图片、一首歌曲、一种服务都是一种资源。文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。这些资源的格式就是表现层（Representation）。
你可以用一个URI（统一资源标识符）指向它，每种资源对应一个特定的URI。
要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而URI应该只代表"资源"的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。
2、状态转化（State Transfer）
互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。
HTTP协议是无状态的，如何用无状态的HTTP协议使服务器发生状态改变呢？这就需要使用HTTP协议里面，常用的4个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。
综合上面的解释，我们总结一下什么是RESTful架构：
（1）每一个URI代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。
二、RESTful API设计原则
1、URL设计
（1）URL 的命名必须全部小写；
（2）URL 中资源（resource）的命名必须是名词，并且应该是复数形式。
（3）URL 必须是易读的
（4）URL 一定不可暴露服务器架构
（5）接口版本号最好放入头部信息中
反例：
https://api.example.com/getUserInfo?userid=1
https://api.example.com/getusers
https://api.example.com/sv/u
https://api.example.com/cgi-bin/users/get_user.php?userid=1正例：
https://api.example.com/zoos
https://api.example.com/animals
https://api.example.com/zoos/{zoo}/animals
https://api.example.com/animal_types
https://api.example.com/employees
2、HTTP动词
常用的HTTP动词有如下5个（括号内对应服务器操作）
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。还有两个不常用的HTTP动词。
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。下面是一些例子：
| 请求方法 |
URL |
描述 |
| GET |
/zoos |
列出所有的动物园(ID和名称，不要太详细) |
| POST |
/zoos |
新增一个新的动物园 |
| GET |
/zoos/{zoo} |
获取指定动物园详情 |
| PUT |
/zoos/{zoo} |
更新指定动物园(整个对象) |
| PATCH |
/zoos/{zoo} |
更新动物园(部分对象) |
| DELETE |
/zoos/{zoo} |
删除指定动物园 |
| GET |
/zoos/{zoo}/animals |
检索指定动物园下的动物列表(ID和名称，不要太详细) |
| GET |
/animals |
列出所有动物(ID和名称)。 |
| POST |
/animals |
新增新的动物 |
| GET |
/animals/{animal} |
获取指定的动物详情 |
| PUT |
/animals/{animal} |
更新指定的动物(整个对象) |
| PATCH |
/animals/{animal} |
更新指定的动物(部分对象) |
| GET |
/animal_types |
获取所有动物类型(ID和名称，不要太详细) |
| GET |
/animal_types/{type} |
获取指定的动物类型详情 |
| GET |
/employees |
检索整个雇员列表 |
| GET |
/employees/{employee} |
检索指定特定的员工 |
| GET |
/zoos/{zoo}/employees |
检索在这个动物园工作的雇员的名单(身份证和姓名) |
| POST |
/employees |
新增指定新员工 |
| POST |
/zoos/{zoo}/employees |
在特定的动物园雇佣一名员工 |
| DELETE |
/zoos/{zoo}/employees/{employee} |
从某个动物园解雇一名员工吧 |
3、URL参数
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
下面是一些常见的参数。
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
4、返回结果
所有的 API 响应，必须 遵守 HTTP 设计规范，必须选择合适的 HTTP 状态码。一定不可所有接口都返回状态码为 200 的 HTTP 响应，如：
HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"code": -1,
"msg": "该活动不存在",
}正确的应该如下：
HTTP/1.1 401 Unauthorized
Server: example.com
Content-Type: application/json
{
"error_code":40100,
"msg": "Unauthorized:操作失败",
}服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
注意：所有 API 一定不可 返回 1xx 类型的状态码。当 API 发生错误时，必须 返回出错时的详细信息。只有来自客户端的请求被正确的处理后才能返回 2xx 的响应，所以当 API 返回 2xx 类型的状态码时，前端 必须 认定该请求已处理成功。
5、其他
（1）API的身份认证应该使用OAuth 2.0框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
三、代码实现
以Spring为例，在实现RESTful架构风格的时候注意一下几点：
1、目标方法上面使用@RequestMapping注解，规范和限制Http请求的请求方法。
@RequestMapping(value = "user", method = RequestMethod.PUT)
@RequestMapping(value = "user/{ids}", method = RequestMethod.DELETE)或者使用
@GetMapping(value = "user")
@PostMapping(value = "user")RequestMethod的取值有：
GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE
2、规定返回状态码及返回数据的基本格式
public ResponseEntity(T body, MultiValueMap headers, HttpStatus status) 返回ResponseEntity对象。ResponseEntity可以设置响应头Header，响应状态码status和响应体body。其中响应状态码为HttpStatus与HTTP状态码相对应。
参考文章（大部分摘自这两篇文章）：
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
https://godruoyi.com/posts/resetful-api-design-specifications
四川乐山程序员联盟【571814743】，欢迎回家！