# Restful API
>[success]`Restful API`是目前`Web API` 设计中比较流行的一种设计风格。
## Restful API
>[info]RESTful是一种软件架构风格、设计风格，而**不是**标准，只是提供了一组设计原则和约束条件。
>[danger]对于这种风格，ThinkPHP框架和laravel框架都给了很好的支持。
### 一、常用的HTTP动词
>[success]这种风格对于熟悉ThinkPHP框架的应该都比较熟悉。
~~~
* GET：读取(Read)
* POST：新建(Create)
* PUT：更新(Update)
* PATCH：更新(Update)，通常是部分更新
* DELETE：删除(Delete)
~~~
>[danger]大家可能会发现，通常情况下的网络请求主要是`POST`和`GET`。通常情况下客户端是不支持除`GET`和`POST`之外的请求方式的。这里的解决方案就是：客户端发出的 HTTP 请求，要加上`X-HTTP-Method-Override`属性，来指定请求方式。
~~~http
POST /api/Person/4 HTTP/1.1
X-HTTP-Method-Override: PUT
~~~
### 二、URI与URL
#### URI
>[info]URI，统一资源标志符(Uniform Resource Identifier， URI)，表示的是web上每一种可用的资源
URI通常由三部分组成：
①访问资源的命名机制；
②存放资源的主机名；
③资源自身的名称。
#### URL
>[danger]URL是URI的一个子集。
URL的格式由三部分组成：
①第一部分是协议(或称为服务方式)。
②第二部分是存有该资源的主机IP地址(有时也包括端口号)
③第三部分是主机资源的具体地址，如目录和文件名等。
### 三、端点设计
>[success]端点是指用于访问API的URI
设计原则
1. 短小便于输入的URI
2. 人可以读懂的URI
3. 没有大小写混用的URI
4. 修改方便的URI
5. 不会暴漏服务器端架构的URI
6. 规则统一的URI
例：
|目的|端点|方法|
|-|-|-|
|获取用户信息列表|http://api.yifeng.com/v1/users|GET|
|新用户注册|http://api.yifeng.com/v1/users|POST|
|获取特定用户信息|http://api.yifeng.com/v1/users/:id|GET|
|更新用户信息|http://api.yifeng.com/v1/users/:id|PUT/PATCH|
|删除用户信息|http://api.yifeng.com/v1/users/:id|DELETE|
### 四、HTTP状态码
客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。当然，也可以根据需求再返回一个 业务状态码。具体的规范可以自行设定。
HTTP 状态码就是一个三位数，分成五个类别。
|状态码|含义|
|-|-|
|1字头|消息|
|2字头|成功|
|3字头|重定向|
|4字头|客户端原因引起的错误|
|5字头|服务器端原因引起的错误|
主要的状态码
|状态码|名称|含义|
|-|-|-|
|200|OK|请求成功|
|201|Created|请求成功，新资源建立|
|202|Accept|请求成功|
|204|No Content|请求成功,没有内容|
|300|Multiple Choices|存在多个资源|
|301|Moved Permanently|资源被永转移|
|302|Found|请求的资源被暂时转移|
|303|See Other|引用他处|
|400|Bad Request|请求不正确|
|401|Unauthorized|需要认证|
|403|Forbidden|禁止访问|
|404|Not Found|没有找到指定的资源|
|429|Too Many Requests|访问次数过多|
|500|Internal Server Error|服务器端发生错误|
|503||服务器暂时停止运营
>[danger]关于状态码这一块大家可以到百度上去了解一下。业务状态码是咱们自行定义的！
### 五、服务器回应
>[success]一般情况下，服务器不要回复纯文本的数据，通常情况下返回的是`XML`或`JSON`格式的数据。
>[danger] Web API其实就是网页的一种，其返回的数据形式更容易让计算机程序处理，而不是返回普通的HTML。所以返回的数据应该尽可能地设计得方便计算机程序处理。
>[info]在这里就使用JOSN作为返回的数据格式。
#### 数据格式返回的指定方法
1. 使用查询参数的方法
2. 使用扩展名的方法
3. 使用在请求首部指定媒体类型的方法
>[danger]如果您的接口不需要同时支持多种类型，也可以不需要进行执定。
>[danger]在返回数据时，在满足需求的情况下，返回的数据量越小越好。(可以让用户来决定返回的数据)
#### 返回数据的封装
>[info]关于响应返回的数据格式，建义封装成统一样的格式。
### 六、版本号
>[success]关于版本号的，有多种解决方案。在这里使用ThinkPHP自带的解决方案。
### 七、API接口文档
>[success]通常情况下，API接口的开发者和使用者是不同的人群，所以做一详细的接口文档是十分必要的。
