在 Web 应用开发的过程中,后端开发人员需要频繁的交付 API 接口,前端开发人员需要频繁的调用 API 接口。为了降低沟通成本、预防可能的安全风险,遵循约定优于配置的原则,有必要规范 API 的接口规范。Restful API 是以资源为核心的 API 设计思路,所有的操作都是针对特定的资源进行。在 SaaS 开发中,推荐使用 Restful API 风格接口,本文主要讨论 Restful API 在 SaaS 开发过程中的一些前置约定。
1. 请求规范
1.1 编码方式
统一采用 charset=utf-8Ajax 全局配置
|
|
Axios 全局配置
|
|
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 ) |
|
|
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 的正则匹配获取参数
|
|
- 使用 Django Forms 获取参数
|
|
2.4 权限校验
- 垂直越权普通用户不允许访问管理员用户资源
- 平行越权普通用户不能访问没有授权的其他普通用户资源
3. 错误码规范
3.1 错误码设计
- 合理的设计错误码
参考设计1
HTTP状态码 | 服务模块代码 | 具体错误代码 |
参考设计2ERROR_INVALID_FUNCTIONERROR_PATH_NOT_FOUNDERROR_TOO_MANY_OPEN_FILESERROR_ACCESS_DENIED
3.2 错误提示应准确并有用
需要提供两个基本内容:
- 返回错误状态,解释原因
- 提示用户如何解决
例如:
- 调用 XXX 接口异常,请稍后重试,或联系管理员 XXX
- 连接 MySQL 数据库异常,请联系管理员 XXX
- 您输入的 XXX 不符合格式要求,请输入 XXX 格式的数据
3.3 提供错误说明对照表
提供一个页面或接口,展示错误码-错误详情的信息。例如:接口 /api/v1/error_code/
,返回:
|
|
4. 参考
- http://www.ruanyifeng.com/blog/2014/05/restful_api.html