Please enable Javascript to view the contents

API 接口规范

 ·  ☕ 3 分钟

在 Web 应用开发的过程中,后端开发人员需要频繁的交付 API 接口,前端开发人员需要频繁的调用 API 接口。为了降低沟通成本、预防可能的安全风险,遵循约定优于配置的原则,有必要规范 API 的接口规范。Restful API 是以资源为核心的 API 设计思路,所有的操作都是针对特定的资源进行。在 SaaS 开发中,推荐使用 Restful API 风格接口,本文主要讨论 Restful API 在 SaaS 开发过程中的一些前置约定。

1. 请求规范

1.1 编码方式

统一采用 charset=utf-8

Ajax 全局配置

1
2
3
$.ajaxSetup({
  contentType: "application/json; charset=utf-8"
});

Axios 全局配置

1
axios.defaults.headers.common['Content-Type'] = 'application/json;charset=UTF-8'

1.2 请求方法

API 的 Method,要符合实际请求的类型。

动词 含义
GET 查看
POST 创建
DELETE 删除
PUT 更新

1.3 传参方式

  • GET 请求
    参数放在请求路径后以 ? 开头的参数串中,参数以 urlencode 编码。

  • PUT / PATCH / POST 请求
    对于复杂数据结构的传参,建议将参数 JSON 编码后放在请求体中。

1.4 请求参数

  • 批量数据必须排序,例如: ?sortOrder=asc&sortField=created_time
  • 批量数据必须分页,例如:?page=5&pagesize=50
  • 可以批量请求的 API,不允许轮询,例如:?id=1,2,3

2. 响应规范

2.1 统一的返回格式

字段名 返回内容描述
result True/False
code 现阶段可以不使用, 0代表正确,非0 代表不同的错误情况
data 成功时,返回的数据的内容
message 失败时,返回的错误信息
request_id (可选)标识请求的id(可以自动生成的唯一标识,方便追踪请求记录 uuid )
1
2
3
4
5
6
{
    'result': True,
    'message': '',
    'data': [],
    'code': 0
}

2.2 合适的状态码

建议充分利用 HTTP Status Code 作为响应结果的基本状态码,基本状态码不能区分的 status,再用响应中"约定"的code进行补充。

  • 200 : GET 请求成功,及 DELETE 或 PATCH 同步请求完成,或者 PUT 同步更新一个已存在的资源
  • 201 : POST 同步请求完成,或者 PUT 同步创建一个新的资源
  • 401 : Unauthorized : 用户未认证,请求失败
  • 403 : Forbidden : 用户无权限访问该资源,请求失败
  • 429 : Too Many Requests : 因为访问频繁,你已经被限制访问,稍后重试
  • 500 : Internal Server Error : 服务器错误,确认状态并报告问题

http状态码详细说明请参考:
https://zh.wikipedia.org/wiki/HTTP%E7%8A%B6%E6%80%81%E7%A0%81

2.3 参数获取方式

  • 使用 Django URL 的正则匹配获取参数
1
url(r'^area/(?P<cityID>\d{6})/$', 'get_area')
  • 使用 Django Forms 获取参数
1
2
3
4
5
6
7
8
9
class FilterForm(forms.Form):
    sys_type = forms.ChoiceField(choices=choices.SYS_CHOICES, required=True, label=u'类型')

def my_view(request):
    form = FilterForm(request.GET)
    if not form.is_valid():
        # 数据不合法
    else:
        # 通过 form.cleaned_data 获取数据

2.4 权限校验

  • 垂直越权
    普通用户不允许访问管理员用户资源

  • 平行越权
    普通用户不能访问没有授权的其他普通用户资源

3. 错误码规范

3.1 错误码设计

  • 合理的设计错误码

参考设计1

200 05 02
HTTP状态码 服务模块代码 具体错误代码

参考设计2

ERROR_INVALID_FUNCTION
ERROR_PATH_NOT_FOUND
ERROR_TOO_MANY_OPEN_FILES
ERROR_ACCESS_DENIED

3.2 错误提示应准确并有用

需要提供两个基本内容:

  • 返回错误状态,解释原因
  • 提示用户如何解决

例如:

  • 调用 XXX 接口异常,请稍后重试,或联系管理员 XXX
  • 连接 MySQL 数据库异常,请联系管理员 XXX
  • 您输入的 XXX 不符合格式要求,请输入 XXX 格式的数据

3.3 提供错误说明对照表

提供一个页面或接口,展示错误码-错误详情的信息。例如:接口 /api/v1/error_code/,返回:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "http_status_code - error_code - message": [
    [
      412,
      "Error_LOGIN_FRONT_NOT_GIFT",
      "礼品不充足"
    ],
    [
      503,
      "ERROR_FAULT",
      "服务器内部错误"
    ]
  ]
}

4. 参考


微信公众号
作者
微信公众号