API 设计建议

iBit程序猿 2021年08月10日 558次浏览

URI资源

使用具体名词

要描述你所拥有的资源, 使用具体名词代替行为动词(指API命名方式),使用单数(很多书籍用的是复数)

资源id

URI中的资源id只能跟在资源后面,表示资源的一个实例。否则,放在参数中,作为过滤条件。

eg: 查找id为"12"的公司下的员工

/v1.0.0/api/company/12/employee   # "12"跟在"company"后,表示id为"12"的公司
或者
/v1.0.0/api/employee?companyId=12 # "companyId=12" : 作为过滤条件

URI 命名

使用 蛇形命名法snake_case)给项目中的资源(组合名词)命名,使用小写

eg:

contract : 单个名词
current_user : 组合名词,由current和user组成。

版本号

版本号的格式为v\d+.\d+.\d+, 采用3段式,版本号放在域名后面

eg:

http://api.ibit.tech/v1.0.0

api

api标识放置于版本号后面

eg:

http://api.ibit.tech/v1.0.0/api

资源操作

HTTP动词

使用HTTP相关的动词来描述对资源的操作

  • GET : 对资源的检索,对资源不会产生影响
  • POST : 创建资源
  • PUT : 修改资源
  • DELETE : 删除资源

eg:

GET /v1.0.0/api/company       - # 获取公司列表
GET /v1.0.0/api/company/12    - # 获取id为"12"的公司
GET /v1.0.0/api/company/12/employee - # 获取id为"12"的公司下的员工列表 
等价于:GET /v1.0.0/api/employee?companyId=12
POST /v1.0.0/api/company      - # 创建公司
POST /v1.0.0/api/company/12/employee - # 给id为"12"的公司创建员工
PUT /v1.0.0/api/company/12    - # 修改id为"12"的公司
DELETE /v1.0.0/api/company/12 - # 删除id为"12"的公司 

如果我们需要修改某个特定资源的某个属性,可以使用

PUT /v\d+.\d+.\d+/api/resouce/$resource_id/attribute_name

eg:

PUT /v1.0.0/api/company/12/status - # 修改id为"12"的公司的"status"

自定义动词

如果以上HTTP相关的动词不能满足对资源操作的描述,可增加自定义动词,采用自定义动词时只能采用POST的请求方式,在资源或资源id后增加 /{自定义动词},如当表述公司员工信息导入确认的语义时,可以用如下url表述:

# 公司员工信息导入确认
POST /v1.0.0/api/company/{companyId}/employee/import/confirm

Response

返回格式

{
  "code": Integer,      //状态码(http response status一致)
  "data": Object,       //返回数据
  "message": String,    //业务定义的返回码
  "messageCN": String,  //业务定义的中文消息
  "requestId": String,  //请求id,唯一,用于日志跟踪
  "timestamp": Long     //系统时间戳
}

返回json, 成功时(code=200),messageS_OK,失败时message为定义好的具有业务意义的字符串,如B10011001, P10011001, B: 表示业务错误,P: 表示参数错误,字母后面跟8位数字,前4位表示大类,后4位自增长数字。data是对象(对应前端就是map)。

eg:

{
  "code": 200,
  "data": {},
  "message": "S_OK",
  "messageCN": "成功",
  "requestId": "cxaaaaabbyAaRBlEaaf",
  "timestamp": 1512457759052
}

code描述

同 HttpResponse.status,不过只采用下述几种。

   200: 操作成功
   400: 参数错误
   401: 无权限
   404: 资源不存在
   500: 系统错误