1. 微服务清单

业务接口分类 微服务id
BOS3D bos3dengine

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应用: 调用 应用登录 接口。

3. API请求与返回格式

3.1. API请求参数格式

API请求参数以Headers、Search Parameters、Path Parameters和Body(适用于POST、PUT)等形式传递:

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响应数据格式

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 500 -> 服务器遇到错误,无法完成请求

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

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

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

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

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

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

l HTTP Body(HTTP消息主体)

通常情况下,API响应消息主体格式如下:

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

其中:code为响应代码,message为响应消息,data为响应数据。

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

特殊情况:当下载文件时,HTTP body为特定格式的文件。

3.3. 通用错误响应

3.3.1. 接口地址错误

调用一个不存在的接口时,响应如下:

HTTP Status Code:404
Body:
{
    "timestamp": "2018-06-30T06:31:22.551+0000",
    "status": 404,
    "error": "Not Found",
    "message": "No handler found for POST /api/models/120749/components",
    "path": "/api/models/120749/components"
}

3.3.2. 接口方法错误

使用错误的Method调用接口时(比如使用GET调用一个POST接口),响应如下:

HTTP Status Code:405
Body:
{
    "timestamp": "2018-06-30T06:33:01.121+0000",
    "status": 405,
    "error": "Method Not Allowed",
    "message": "Request method 'GET' not supported",
    "path": "/api/models/120749/components"
}

3.3.3. 接口Body参数为空错误

调用需要设置body参数的接口时,如果Body为空,相应如下:

HTTP Status Code:200
Body:
{
    "message": "body不能为空",
    "code": "BAD_PARAMETER",
    "data": null
}

3.3.4. 接口参数类型错误

请求参数类型不符合要求时(比如接口要求Body为JSON对象,调用时Body为空格、数字、字符串或JSON数组),响应如下:

HTTP Status Code:400
Body:
{
    "message": "错误请求",
    "code": "BAD_REQUEST",
    "data": null
}

注:此响应格式仅适用于Spring框架自动参数校验

3.3.5. 请求路径或Body中缺少必传参数

HTTP Status Code:200
Body:
{
    "message": "参数(XXX)不能为空",
    "code": "PARAMETER_REQUIRED",
    "data": null
}

3.3.6. 请求的资源不存在

HTTP Status Code:200
Body:
{
    "message": "XXX(xxx)不存在",
    "code": "XXX_NOT_FOUND",
    "data": null
}

具体如下:

代码(code) 消息(message)
DATABASE_NOT_FOUND 数据库(xxx)不存在
MODEL_NOT_FOUND 模型(xxx)不存在
COMPONENT_NOT_FOUND 构件(xxx)不存在
FILE_NOT_FOUND 文件(xxx)不存在
SCENE_NOT_FOUND 场景(xxx)不存在
GLTF_NOT_FOUND glTF(XXX)不存在
PACKAGE_NOT_FOUND 离线数据包(XXX)不存在
OUTLINE_NOT_FOUND 外轮廓(XXX)不存在
COMPARE_NOT_FOUND 对比(XXX)不存在
TREE_NOT_FOUND 模型树(XXX)不存在
DRAWING_NOT_FOUND 图纸(XXX)不存在
ROUTE_NOT_FOUND 路网(XXX)不存在
DRAWINGELEMENT_NOT_FOUND 图元(XXX)不存在
APP_NOT_FOUND BOS应用(XXX)不存在

3.3.7. 系统错误

HTTP Status Code:500
Body:
{
    "message": "服务器内部错误",
    "code": "INTERNAL_ERROR",
    "data": null
}

3.3.8. 用户身份验证失败

HTTP Status Code:401
Body:
{
    "message": "无法获取账户",
    "code": "ACCOUNT_NO_EXIST",
    "data": null
}

3.3.9. 用户权限验证失败

HTTP Status Code:403
Body:
{
    "message": "权限不足",
    "code": "NO_PERMISSION",
    "data": null
}

3.3.10. BOS应用创建者的订阅已过期

HTTP Status Code:423
Body:
{
    "message": "订阅账号已到期",
    "code": "ACCOUNT_SUBSCRIBE_EXPIRE",
    "data": null
}
版权所有@盈嘉互联(北京)科技有限公司 京ICP备15051988号-9 Copyright © 2021 all right reserved,powered by Gitbook该文件修订时间: 2021-08-25 16:13:00

results matching ""

    No results matching ""