在 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
2

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

1.2 请求方法

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

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 统一的返回格式

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

参考设计 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

{
  "http_status_code - error_code - message": [
    [412, "Error_LOGIN_FRONT_NOT_GIFT", "礼品不充足"],
    [503, "ERROR_FAULT", "服务器内部错误"]
  ]
}

4. 参考

• http://www.ruanyifeng.com/blog/2014/05/restful_api.html