RESTful API开发规范

女生的网名这么多〃 提交于 2019-12-07 06:41:13

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

        }

}

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!