API接⼝规范

API接⼝规范"/>

API接⼝规范

API接⼝规范

约束

• 与前端交互以及对外交互,统⼀采⽤HTTPS协议，以确保交互数据的传输安全.
• 内部微服务之间调⽤HTTP协议.
• 接⼝采⽤Restful⻛格,url格式不出现动词.
• url全⼩写格式,单词组合⽤中划线.

例如: /api/user-group

• 所有字段，⽆特殊声明下，都使⽤驼峰命名

请求⽅式

GET（SELECT）： 从服务器取出资源（⼀项或多项）。
POST（CREATE）： 在服务器新建⼀个资源。
PATCH（UPDATE）： 在服务器更新资源，请求时传递变更的属性
PUT（UPDATE）： 在服务器更新资源，请求时传递完整的属性
DELETE（DELETE）： 从服务器删除资源。
例⼦：
GET /api/id-base/v5/user/{userId} 查询指定⽤户信息
GET /api/id-base/v5/users 获取全部⽤户信息
POST /api/id-base/v5/user 新建⼀个⽤户
PATCH /api/id-base/v5/user/{userId} 修改⽤户信息，请求时传递变更的属性
PUT /api/id-base/v5/user/{userId} 修改⽤户信息，请求时传递完整的⽤户信息
DELETE /api/id-base/v5/user/{userId} 删除指定⽤户

路径规则

完整url路径格式为

http(s)://域名(:端⼝)/中⼼-微服务/版本号/接⼝名称

例如: 身份中⼼提供的接⼝
前端访问地址为：

/{userId}

后端提供地址为：

https://ip:port/v5/user/{userId}

前后端通讯时间格式

统⼀使⽤13位数字类型的时间，例如：1544154563599

请求说明

• 访问IDaas平台微服务的请求(⽹关解析后):
  headers 中必须有下列参数:

tenantId: Long
userId: Long

• body说明
  默认为json格式

响应说明

• HttpStatus: 成功为200，客户端请求异常、业务异常为 400，服务端内部异常为 500，遵守HttpStatus的基本定
  义
• 响应头

 "traceId": "string", // 跟踪id

• 响应体:

{ "code": "string", // 成功响应为 0, 失败响应为 各个中⼼定义的异常码"timestamp": long, // 13位 服务器时间戳 例如：1544154563599"error": "string", // 错误提示，成功响应没有该字段 "result": ? // 返回结果数据, 数据类型为后端定义的string、list、object等json数据类型。scim2协议要求的内容也
在result中，scim2协议字段单独说明
}

示例:
成功响应1:

{"code": "0", // 成功响应为 0"timestamp":1544154563599 //服务器时间戳
}

成功响应2:

{"code": "0", // 成功响应为 0"timestamp":1544154563599, //服务器时间戳"result": 3 // 基础数据类型
}

成功响应3 - json array:

{"code":"0","timestamp":"","result":[{// json}]
}

成功响应4–分⻚:

{"code":"0","timestamp": 1544154563599,"result":{"current": 0, //当前⻚"pages": 0, //总⻚数"records": [{// 单条详情json数据}],"searchCount": true,"size": 0, //当前⻚多少条"total": 0 //总条⽬数}
}

成功响应5–scim2

//scim2协议中要求的字段将单独另⽂说明
{"code":"0","timestamp": 1544154563599,"result":{//以下为scim2的格式"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],"id": "2819c223-7f76-453a-919d-413861904646","userName": "bjensen@example","meta": {"resourceType": "User","createAt": 1544154563599,"updateAt": 1544154563599,"version": "3694e05e9dff590","location": ""}}
}

失败响应:

{"code": "010200013000", // 错误码"timestamp":1544154563599, //服务器时间戳"error": "⽤户名或密码不正确" // 错误信息
}

附录1： 通⽤业务字段

附录2： 通⽤查询参数

• type 表示对象类型
• field 表示对象的属性名
• 示例代码：
  s/dto/QueryCondition.java
• 具体⽀持哪些查询语法由具体的接⼝定义
  | 操作 | 说明
  |
  | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------
  ------------------------------------------------- |
  | fields[{type}] | 需要返回的字段，可过滤嵌套的字段，eg：fields[users]=id,name 表示 仅返回⽤户对象的
  id,name |
  | search[{field}] | 模糊查询,仅⽀持不同字段and连接,不⽀持id的模糊查询，eg: search[name]=name1 表示
  name like ‘%name1%’ |
  | searchL[{field}] | 左模糊查询,仅⽀持不同字段and连接,不⽀持id的模糊查询，eg: searchL[name]=name1 表
  示 name like ‘%name1’ |
  | searchR[{field}] | 右模糊查询,仅⽀持不同字段and连接,不⽀持id的模糊查询，eg: searchR[name]=name1
  表示 name like ‘name1%’ |
  | searchOr[{field}] | 模糊查询，逻辑或连接,仅⽀持不同字段OR连接,不⽀持id的模糊查询，eg:
  searchOr[type]=enum1&searchOr[name]=name1 表示 type like ‘%enum1%’ or name like ‘%name1%’
  |
  | filter[{field}] | 等于，相同字段or，不同字段and，eg:
  filter[type]=user&filter[type]=userGroup&filter[name]=name1 表示 (type = ‘userGroup’ or type = ‘user’) and
  name = ‘name1’ |
  | filterOr[{field}] | 等于，逻辑或连接，相同字段or，不同字段or，eg:
  filterOr[type]=user&filterOr[type]=userGroup&filterOr[name]=name1 表示 (type = ‘userGroup’ or type =
  ‘user’) or name = ‘name1’ |
  | neq[{field}] | 不相等,相同字段and,不同字段and，eg:
  neq[type]=user&neq[type]=userGroup&neq[name]=name 表示 (type <> ‘userGroup’ and type <> ‘user’) and
  name <> ‘name1’ |
  | lt[{field}] | ⼩于,仅⽀持不同字段and连接，eg: lt[age]=20 表示 age < 20
  |
  | lte[{field}] | ⼩于等于,仅⽀持不同字段and连接，eg: lte[age]=20 表示 age <= 20
  |
  | gt[{field}] | ⼤于, 仅⽀持不同字段and连接，eg: gt[age]=20 表示 age > 20
  |
  | gte[{field}] | ⼤于等于，仅⽀持不同字段and连接，eg: gte[age]=20 表示 age >= 20
  |
  | sort | 排序，eg1: sort=-name,age 表示 按照name的倒叙和age升序排序；eg2: sort=-name,-age 表
  示 按照name的倒叙和age倒叙排序 |
  | page[{current,size}] | 分⻚查询，current ⻚码，从1开始, ⼤于0，缺省1; size ⼀⻚的⼤⼩，⼤于0, 缺省10，最
  ⼤1000; 例如: page[current]=1&page[size]=5 表示 取 第1⻚的5条数据的数据 |

服务注⼊规范

作为资源地址注⼊到系统api需要加⼊⾃⼰的服务名字例如meta微服务下⾯的api /resource/get-all 注⼊到应⽤的
资源表的url就应该是/meta/resource/get-all