REST接口和HTTP幂等性

REST接口

REST 用来规范应用如何在 HTTP 层与 API 提供方进行数据交互 。REST 描述了 HTTP 层里客户端和服务器端的数据交互规则；客户端通过向服务器端发送 HTTP（s）请求，接收服务器的响应，完成一次 HTTP 交互。这个交互过程中，REST 架构约定两个重要方面就是 HTTP 请求所采用的方法，以及请求的链接。

在请求层面，REST 规范可以简单粗暴抽象成以下两个规则：

1.请求 API 的 URL 表示用来定位资源。
2.请求的 METHOD 表示对这个资源进行的操作。

URI语法

URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]

scheme: 指底层用的协议，如http、https、ftp
host: 服务器的IP地址或者域名
port: 端口，http中默认80
path: 访问资源的路径，就是咱们各种web 框架中定义的route路由
query: 为发送给服务器的参数
fragment: 锚点，定位到页面的资源，锚点为资源id

URL规则

1 名词对应数据库中的表
2 URL中不能有动词
3 URL结尾不应该包含斜杠“/”
4 正斜杠分隔符”/“必须用来指示层级关系
5 使用连字符”-“来提高URL的可读性，而不是使用下划线”_”
6 URL路径中首选小写字母
7 URL路径名词均为复数

HTTP动词

对于URL资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

  GET（SELECT）：从服务器取出资源（一项或多项）。
  POST（CREATE）：在服务器新建一个资源。
  PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  DELETE（DELETE）：从服务器删除资源。

资源过滤

如果只需要查询某些条件的数据API应该提供参数，过滤返回结果。
常见的参数：

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?teacher_subject=语文：指定筛选条件

返回

返回状态码推荐标准HTTP状态码

有很多服务器将返回状态码一直设为200，然后在返回body里面自定义一些状态码来表示服务器返回结果的状态码。
由于REST API是直接使用的HTTP协议，所以它的状态码也要尽量使用HTTP协议的状态码。

200 OK 服务器返回用户请求的数据，该操作是幂等的
201 CREATED 新建或者修改数据成功
204 NOT CONTENT 删除数据成功
400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
401 Unauthoried 表示用户没有认证，无法进行操作
403 Forbidden 用户访问是被禁止的
422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等

返回结果

GET /teachers 返回资源列表
GET /teachers/:id 返回单独的资源
POST /teachers 返回新生成的资源对象
PUT /teachers/:id 返回完整的资源对象
PATCH /teachers/:id 返回被修改的属性
DELETE /teachers/:id 返回一个空文档

HTTP幂等性

HTTP幂等方法，是指无论调用这个url多少次，都不会有不同的结果的HTTP方法。也就是不管你调用1次还是调用100次，1000次，结果都是一样的（前提是服务器端的数据没有被人为手动更改。比如说，你数据库中的数据被手动更改过，那两次调用的结果肯定是变化的）。

HTTP GET方法，用于获取资源，不管调用多少次接口，结果都不会改变，所以是幂等的

只是查询数据，不会影响到资源的变化，因此我们认为它幂等。

HTTP POST方法是一个非幂等方法，因为调用多次，都将产生新的资源

HTTP PUT方法因为它直接把实体部分的数据替换到服务器的资源，我们多次调用它，只会产生一次影响，但是有相同结果的 HTTP 方法，所以满足幂等性。

HTTP PATCH方法是非幂等的。HTTP POST方法和HTTP PUT方法可能比较好理解，但是HTTP PATCH方法只是更新部分资源，怎么是非幂等的呢?
因为，PATCH提供的实体则需要根据程序或其它协议的定义，解析后在服务器上执行，以此来修改服务器上的资源。换句话说，PATCH请求是会执行某个程序的，如果重复提交，程序可能执行多次，对服务器上的资源就可能造成额外的影响

HTTP DELETE方法用于删除资源，会将资源删除。调用一次和多次对资源产生影响是相同的，所以也满足幂等性。