Restful API 设计规范

2021-03-22 17:58
46
0

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、客户端兼容性

有很多客户端目前只接受GETPOST方法,为了方便服务器端区分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:服务器无法处理请求,一般用于网站维护状态。

全部评论