API规范
REST API规范
基本规则
除特殊说明外，Web API遵循如下基本原则：
l BIM工作平台以RESTful Web Service的形式提供API。
l 基于安全性考虑，BIM工作平台API需要使用SSL加密传输协议（HTTPS）进行访问。
l BIM工作平台使用OAuth 2.0协议进行API访问授权控制。
l 业务系统在访问BIM工作平台API前，需要获得BIM工作平台颁发的应用密钥（APP_KEY和APP_SECRET），并赋予相应的API授权范围。
请求方法
BIM工作平台Web API使用GET、POST、PUT、DELETE等4个标准HTTP请求方法，用于对资源进行访问、创建、修改和删除等标准操作。
l GET：幂等操作，通常用于表达“获取”、“查询”等语义。典型使用场景包括：获取特定资源信息；根据指定条件查询资源信息。
l POST：非幂等操作，通常用于执行“新建”、“创建”等语义。典型使用场景包括：创建一个或多个新的资源； 执行需要大量数据输入的查询；执行不安全或非幂等操作，但其他HTTP方法看上去不适合时。
l PUT：幂等操作，通常用于执行“修改”、“更新”等语义。典型使用场景包括： 更新一个或多个资源；在应用能够决定资源URL的情况下，创建一个资源。
l DELETE：幂等操作，通常用于执行“删除”语义。典型使用场景包括：删除一个或多个资源。
API设计
l 版本控制
为了给客户端提供一致的api接口界面，禁止在url上增加版本段，而采用header方式进行传递
示例如下：
错误：GET /v2/models
正确：GET /models，同时在header中传递“Accept-Version: v2”
Spring mvc 的实现如下：
@RequestMapping(headers = "Accept-Version=v2",value = "models",method = RequestMethod.GET)
l 命名空间
对于每个业务提供的api，需要提供相应的namespace，作为url的最前段，一般而言，命名空间以微服务的名称开头，后面可选跟随具体的业务
示例如下：
正确：GET /model/models # model为namespace
l 单个资源
对于单个资源，支持以下URL
正确：GET /model/models/{id} #获取单个资源
正确：POST /model/models #创建单个资源
正确：PUT /model/models/{id} #更新单个资源
正确：DELETE /model/models/{id} #删除单个资源
正确：PATCH /model/models/{id} #更新单个资源（只传差异）
正确：GET /model/configRuleFile #获取单个资源（如果仅有一个值时，应采用单数方式）
返回结果：
如果指定的资源并不存在，那么应该返回404 Not Found状态，否则应该返回200 OK状态码
l 资源集合
对于资源集合，支持以下URL
正确： GET /model/models #获取资源列表
正确： GET /model/models?ids={ids} #批量获取资源列表
正确： DELETE /model/models?ids={ids} #批量删除资源列表
返回结果：
如果列表为空，则应该空数组
l 资源关联
对于资源的关联，应采用嵌套的方式访问子的单个资源和资源集合
正确：GET /model/models/{modelId}/elements/{elementId} # 获取model中的一个element, models为父资源，elements为子资源
正确：GET /model/models/{modelId}/elements # 获取model中的element列表
l 复杂操作
Api应尽量采用以上标准操作方式实现（如查询资源列表，有多种条件的，应尽量合并到同一个Api中，而不应该拆分成不同的Api）。
对于复杂的操作，不能使用以上标准操作涵盖的，采用在最后增加相关资源描述段的方式处理，对于查询采用GET，对于修改采用POST，对于删除采用DELETE
正确：GET /model/models/basicInfo?buildingId={buildingId} # 根据buildingId获取模型基本信息（不是model的完整信息）
POST /model/models/{modelId}/compare # 执行模型对比
l 过滤
对于每种资源，应尽量选择一种唯一标识（id或code），体现在PathVariable中
对于其余的查询条件，采用RequestParam的方式进行传递
正确：GET /model/models?buildingId={buildingId} # 根据buildingId获取模型列表
DELETE /model/models?buildingId={buildingId} # 根据buildingId删除模型
l 排序
排序字段通过RequestParam方式进行传递
正确：GET /model/models?buildingId={buildingId}&sort=create_time,desc&sort=version
Spring Mvc中采用Sortable进行接收
l 分页
分页参数通过RequestParam方式进行传递
正确：GET /admin/users?keywords=xxx&page=0&size=1&sort=name;desc&sort=sex
Spring Mvc中采用Pageable进行接收
响应结果
BIM平台使用HTTP响应状态码（Status Code）来区分处理成功和不同的失败原因。
典型的响应状态码和含义如下：
| 响应状态码 |
含义 |
|
| 成功 |
200 |
调用成功 |
| 201 |
创建成功 |
|
| 204 |
执行成功，但无返回值 |
|
| 失败 |
400 |
无效请求 |
| 401 |
没有登录 |
|
| 403 |
没有权限 |
|
| 404 |
请求的资源不存在 |
|
| 500 |
服务内部错误 |
其中，对于响应码为200和201的情况，直接返回Json结构的结果数据；对于响应码为500的失败情况，返回如下格式的响应结果：
{
“code”: “”, // 错误的类型
“message”: “”, // 错误信息
“detail”: { // 错误的详细信息，结构随着错误类型的不同而不同
}
}
