API 设计建议

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），message为S_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: 系统错误