API 接口规范

在 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，要符合实际请求的类型。

动词	含义
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
{
  "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