RESTful API开发规范

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”: {  // 错误的详细信息，结构随着错误类型的不同而不同

        }

}