极客嘉园

1、概述

由于前端设备的复杂多样性（web端，pc端，移动端，智能设备端等），为了方便后台与前端更好的通讯，我们选择了时下比较流行的RESTful API 设计规范定义前端调用后端的数据接口。 本文主要讲述RESTFul Api 接口定义标准，供不熟悉其设计规范的同学们学习，并期望在开发工作中大家都遵循该标准进行后续的开发。

2、协议

采用http或https协议，为了安全强烈推荐使用https协议的api接口。

3、 数据格式

最常用的是JSON数据格式

4、http方法

常见的http方法包括：get，post，put，delete。 http方法对应CRUD操作如下：

http method	operation	操作
GET	Read	读取、获取、查询
POST	Create	新建、新增
PUT	Update	更新、修改、编辑
DELETE	Delete	删除、移除

5、api组成

1. 完整的api接口组成：http方法动词 域名/api版号/业务实体名词。 例如:GET https://api.example.com/v1/users 其中https://api.example.com为域名，v1为api版本号，users为业务实体名词,GET为http方法动词。

2. RESTFul 的核心思想就是前端发出的请求的主要格式就是“动词+名词”的结构。 比如这个api接口GET /users，其中GET作为动词表示读取，users作为名词表示多个用户，所以我们从这个接口就可以直接看出这个接口是什么业务需求。而 GET /getUsers or POST /createNewUser 这样的命名就是不符合规范的，这里必须是名词（当然若你非要这么用，也不会影响业务的实现）。

GET      https://api.example.com/v2/user   获取一个用户信息
POST     https://api.example.com/v2/user   新增一个用户信息
PUT      https://api.example.com/v2/user   修改一个用户信息
DELETE   https://api.example.com/v2/user   删除一个用户信息

6、参数

• 路径参数，如下：

  GET      https://api.example.com/v2/user/{phone_number}   通过手机号码获取某一个用户信息
  PUT      https://api.example.com/v2/user/{uid}/{address}   修改某一个用户地址信息
  

• request body参数,如下：

POST     https://api.example.com/v2/user  -d 
{
    "phone_nume": 18812345678,
    "email": "kevin@qq.com",
    "gender": "male",
    "password": "password"
}
新增一个用户信息

7、客户端兼容性

有很多客户端目前只接受GET与POST方法，为了方便服务器端区分POST,PUT,PATCH,DELETE方法，前端在发送http请求时，增加一个X-HTTP-Method-Override`属性。

8、响应结果规范

统一响应格式为json格式，其具体格式如下所示：

        {
         "code": 0,   #响应状态码
         "data": {},  #数据内容，
         "message": "string"  #响应提示信息
        }

• GET方法，统一响应状态码code为200，data为查询的实体信息，message为空
• POST方法，统一响应状态码code为201，data为新建的实体完整信息，message为空
• PUT方法，统一响应状态码code为201，data为修改后的实体完整信息，message为空
• DELETE方法，统一响应状态码code为204，data为空，message为空
• 如果以上几种方法，响应发生错误，响应状态码code为对应错误状态码，message会显示错误信息，data为空。

9、响应状态码

状态码必须精确，常见的http响应状态码包含:

• 2xx：操作成功
• 4xx：客户端错误
• 5xx：服务器错误

客户端错误状态码如下：

• 400 Bad Request：服务器不理解客户端的请求，未做任何处理。

• 401 Unauthorized：用户未提供身份验证凭据，或者没有通过身份验证。

• 403 Forbidden：用户通过了身份验证，但是不具有访问资源所需的权限。

• 404 Not Found：所请求的资源不存在，或不可用。

• 405 Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内。

• 410 Gone：所请求的资源已从这个地址转移，不再可用。

• 415 Unsupported Media Type：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式。

• 422 Unprocessable Entity ：客户端上传的附件无法处理，导致请求失败。

• 429 Too Many Requests：客户端的请求次数超过限额。

服务端错误状态码如下：

• 500 Internal Server Error：客户端请求有效，服务器处理时发生了意外。

• 502 Bad Gateway ：网管坏掉啦。

• 503 Service Unavailable：服务器无法处理请求，一般用于网站维护状态。