1. 访问业务数据管理微服务

如果想访问业务数据管理微服务，可以使用以下格式的 url：

API域名/{service}/{appKey}

其中{service}表示小写的微服务 id，{appKey} 表示应用标识，在后台中占用一个独立的 DB。微服务 id 清单如下：

appKey 为 BOS 应用实例的 Key，一个 BOS 应用实例对应一个唯一 Key。应用在 BOS 中创建后、发布后都将获得对应的 appKey。BOS 中创建后的应用的 appKey 可在「 应用管理 -编辑」获取，BOS 应用发布后可在用户中心或管理员中心应用管理界面获得。

比如想在BOS中调用「某个应用的文档管理微服务的创建文件夹接口」，可使用：

http://bosgw.bimwinner.com/bosdocumentservice/h5e4ff8257dc4e86a8042097f67d2718/folders

2. 数据访问控制

2.1. AccessToken

BOS 应用请求API时，系统使用 AccessToken 进行数据访问控制。

AccessToken：BOS 应用请求的访问标识。用户登录后可获得 AccessToken。

AccessToken 可通过以下2种方式传递：

1. HTTP Header（HTTP请求头）：Authorization:xxxxxxxx

2. URL参数：access_token=xxxxxxxx

AccessToken 有一定的有效期，固定时长（6h）。当 AccessToken 过期时，需要使用更新后的 AccessToken。获取 AccessToken 的方式为：

BOS应用: 调用 应用登录 接口。

2.2. 权限控制

1. 应用创建者拥有对数据模型配置的权限，其他用户没有。

2. 可访问应用的用户默认可以创建数据。

3. 如果应用启用 gacl 数据级权限管理模式，则应用中的实例数据，除了数据创建者外，其他用户只有被授权才可以访问和操作。如果应用未启用 gacl 数据级权限管理模式，则应用中的实例数据被访问或操作时不用校验用户权限。

4. 如果应用启用 gacl 数据级权限管理模式，默认全部对象类都启用数据级权限管理；如果创建对象类的时候指定不启用数据级权限管理，则该对象类的实例数据被调用时不用校验用户权限。

3. 重要业务流程

3.1. API请求参数格式

API请求参数以 Headers、Search Parameters、Path Parameters 和 Body（适用于POST、PUT、复杂的GET）等形式传递：

1. Headers：主要包含 Authorization、Content-Type 等HTTP头部信息。

2. Search Parameters：查询参数，url中的参数。例如：http://x.xx.xx/xx?key=1 中的 key 属于 Search Parameter。

3. Path Parameters：路径参数，url 中的路径参数，例如：http://x.xx.xx/xxx/{key} 中的 key 属于 Path Parameter。

4. Body：对于对象型数据，body 格式为{"参数名":"参数值",……}；对于列表型数据，body 格式为[{},{}]。

3.2. API返回数据格式

3.2.1. HTTP Status Code（HTTP状态码）

• HTTP Status 200 -> 服务器已成功处理了请求

• HTTP Status 400 -> 服务器不理解请求的语法

• HTTP Status 401 -> 请求要求身份验证

• HTTP Status 403 -> 服务器拒绝请求

• HTTP Status 404 -> 服务器找不到请求的资源

• HTTP Status 405 -> 禁用请求中指定的方法

• HTTP Status 406 -> 无法使用请求的内容特性响应请求的资源

• HTTP Status 407 -> 未授权，但指定请求者应当授权使用代理（需要代理授权）

• HTTP Status 408 -> 服务器等候请求时发生超时

• HTTP Status 409 -> 服务器在完成请求时发生冲突

• HTTP Status 410 -> 请求的资源已永久删除

• HTTP Status 411 -> 服务器不接受不含有效内容长度标头字段的请求

• HTTP Status 412 -> 服务器未满足请求者在请求中设置的其中一个前提条件

• HTTP Status 413 -> 请求实体过大，超出服务器的处理能力，服务器无法处理

• HTTP Status 414 -> 请求的 URI（通常为网址）过长，服务器无法处理

• HTTP Status 415 -> 请求的格式不受请求页面的支持

• HTTP Status 416 -> 如果页面无法提供请求的范围，则服务器会返回此状态代码

• HTTP Status 417 -> 服务器未满足"期望"请求标头字段的要求

• HTTP Status 423 -> 资源已锁定

• HTTP Status 500 -> 服务器遇到错误，无法完成请求

• HTTP Status 501 -> 服务器不具备完成请求的功能

• HTTP Status 502 -> 服务器作为网关或代理，从上游服务器收到无效响应

• HTTP Status 503 -> 服务器目前无法使用（由于超载或停机维护）

• HTTP Status 504 -> 服务器作为网关或代理，但是没有及时从上游服务器收到请求

• HTTP Status 505 -> 服务器不支持请求中所用的 HTTP 协议版本

注：除非特殊指明，接口响应代码均为200

3.2.2. HTTP Body（HTTP消息主体）

• 通常情况下，API 响应消息主体格式如下：

{
    "code": "xxx",
    "message": "xxxxx",
    "data": "xxx"
}

• 其中：code 为响应代码，message 为响应消息，data 为响应数据。执行成功的情况下 code 值为 SUCCESS，执行出错的情况 code 值请参考下面表格。

• 对于对象型数据，data 格式为{}；对于列表型数据，data 格式为[{},{}]；data 也可以为 null。

• 特殊情况：当下载文件时，HTTP body 为特定格式的文件。

1. 对于对象型数据，data 格式为：

{
//content
}

例如，http://bosgw.bimwinner.com/bosdocumentservice/xb05cd3a35614caa85c0f8f86c58fcc1/folders/3a0f185b7cbd4fb49d587aeba1c4b43a 的返回数据体为：

{
    "key": "3a0f185b7cbd4fb49d587aeba1c4b43a",
    "bosclass": "folders",
    "code": "folder1", 
    "name": "样例目录",
    "isRoot": "true",
    "description": ""
}

1. 对于列表型数据，data格式为：

[
    {#content1},
    {#content2}
]

例如，http://bosgw.bimwinner.com/bosdocumentservice/xb05cd3a35614caa85c0f8f86c58fcc1/folders 的返回数据体为：

[
    {
        "key": "3a0f185b7cbd4fb49d587aeba1c4b43a",
        "bosclass": "folders",
        "code": "folder1", 
        "name": "样例目录1",
        "isRoot": "true",
        "description": ""
    },
    {
        "key": "3a0f185b7cbd4fb59d587aeba1c4b43a",
        "bosclass": "folders",
        "code": "folder2", 
        "name": "样例目录2",
        "isRoot": "true",
        "description": ""
    }
]

3.3. 错误响应

系统采用统一的错误异常响应，响应的消息主体格式如下：

{
    "code": "xxx",
    "message": "xxxxx",
    "data": NULL
}

具体错误返回清单如下：

4. 业务接口设计

4.1. 一般约定

4.1.1. 实体权限管理

• gacl 实体权限管理仅适用于在创建时设置了启用数据级权限控制的应用。

• gacl 属性标识实体对象类实体的权限信息，其格式如下：

  {
    "gacl": [
        {
            "type": "A",
            "flags": "g",
            "principal": "roles/123",
            "permissions": "r"
        }, // 角色权限示例
        {
            "type": "A",
            "flags": "",
            "principal": "users/me",
            "permissions": "rwdc"
        }, // 用户权限示例
        {
            "type": "A",
            "flags": "",
            "principal": "all",
            "permissions": "rwd"
        } //所有人权限示例
    ],
    "bosclass": "demo"
    //其他属性信息
  }
  

其中:

1. flags：g标识该权限为角色权限，其它为用户权限。

2. principal：用户、角色名、所有人，值为用户、角色名id（格式为对象类基类类名/对象实体key）、all（代表应用内所有用户）。

3. permissions：权限字段。r为可读，w为可写，d为可删，c为控制（具有授权权限）。

4. rwdc 四种权限的约束关系如下：

• gacl数据级权限判定

• 权限判定：用户具有的权限为该用户的权限和该用户对应的所有角色权限的并集。

• 操作对象类数据：获取数据时需具有该数据的读权限（r）；修改数据时需需具有该数据的写权限（w）；删除数据需需具有该数据的删除权限（d），对数据设置权限时需具有该数据的控制权限（c）。

• 操作关系类数据 ：获取、创建、修改、删除数据时需同时具有关联对象的读权限。关联对象指的是关系实例左右关联的实体对象（即关系实例中_from、_to指向的实体对象）。

• 当为 all 时，表示所有用户拥有该数据的访问权限，all 只能有 rwd 权限，不能有 c 权限。

4.1.2. 查询条件说明

• 对于返回多个对象的情况，可在SearchParas上设置查询附加参数，对返回的结果进行属性筛选，下列为查询附加参数说明：

• whitelist=xxx,yyy,zzz 指定返回属性字段，多个属性名用英文逗号隔开。

• limit=10：指定返回记录的数量，值为正整数。

• offset=10：指定返回记录的开始位置，值为正整数。

• page=2&per_page=100：page 指定第几页，per_page 指定每页的记录数，值为正整数。page 为 0 或负整数时默认返回第1页。

• sortby=name&order=asc：sortby 指定返回结果按照哪个属性排序，order 指定排序顺序（值可为 asc 或 desc ），多个属性用英文逗号隔开（按属性顺序依次进行排序，如第一个属性值相同，则按第二个属性值排序，依次类推）。

• 具体适用的接口请见每个接口的说明。

4.1.3. GET方法返回对象内容说明

• 获取某一个实体对象信息时，返回的 body 由参数、关系两部分构成。返回的参数内容由此对象的 bosclass 定义决定，同时包含 gtime、guser、gacl三个内置属性以及 currentUserPermissions 属性（currentUserPermissions 为当前用户（包括用户所属的角色）对该实体的所有权限）；返回的关系为与此对象关联的所有一级关系，用户对返回的实体对象、关联关系涉及的另一实体对象需具有读取权限。以 folders 为例返回内容如下：

  {
    "parameter": {
        "key": "",
        "bosclass": "",
        "code": "",
        "description": "",
        "name": "",
        "gtime": "",
        "guser": "",
        "gacl": [
            {
                "principal": "user/187611711",
                "permissions": "rwdc",
                "flags": ""
            }
        ],
        "currentUserPermissions": "rwdc"
    },
    "relationship": {
        "irFolderDocument": {
            "documents": [
                {
                    "key": "document04_0",
                    "uri": " http://xxx.xxx/documents/document04_0",
                    "relationshipKey": "XXX"
                },
                {
                    "key": "document05_0",
                    "uri": " http://xxx.xxx/documents/document05_0",
                    "relationshipKey": "YYY"
                }
            ]
        }
    }
  }
  

• 说明：当用户通过 SearchParas 的 whitelist 设置对象返回属性时，parameter 部分除了返回 whitelist 中指定的属性外，默认返回key 、gtime、guser、gacl三个内置属性以及 currentUserPermissions 属性。

4.1.4. 关于批量处理数据

所有批量添加、修改、删除接口执行过程中，如遇到数据错误则此条数据不执行，其他正确数据正常执行，并返回执行成功/失败的消息，HTTP状态码为200。当一条数据存在多个错误时，按照校验顺序返回校验发现的第一个错误。

4.1.5. Relationship关系实例数据创建

关联关系实例中，左关联对象实例可为关联关系定义时的左对象类的实例或左对象类的子孙类的实例，右关联对象实例可为关联关系定义时的右对象类的实例或右对象类的子孙类的实例。

4.1.6. 树形结构对象设置

对于启用了树形结构的对象类，系统默认会增加5个属性：parentId、longCode、longName、level、leaf。用户如需在接口中设置对象的树形层次结构，只需传递parentId属性，parentId指向当前对象的父对象成。其中parentId的值为：对象类基类类名/父对象key。

4.1.7. 业务事务控制

对于需要调用多个增删改、授权接口才能实现某个完整业务的事务控制，可通过调用“GET /prototype/transaction启动业务事务” 接口获取事务编码，并在调用增删改、授权接口时传递该业务事务编码（通过SearchParas 中transactionCode参数传递业务事务编码）以表示这些接口的操作处于同一事务中，后续当事务中某个接口执行未按预期时，可通过调用“POST /prototype/transaction/{transactionCode}根据业务事务编码发起事务回滚”接口对处于同一事务中已执行的操作进行回滚，通过事务控制可实现处于同一事务中的接口要么全部执行成功，要么全部不执行。