1. 微服务清单
业务接口分类 | 微服务id |
---|---|
BOS3D | bos3dengine |
2. 数据访问控制
2.1. AccessToken
BOS 应用请求API时,系统使用 AccessToken 进行数据访问控制。
AccessToken:BOS 应用请求的访问标识。用户登录后可获得 AccessToken。
AccessToken 可通过以下2种方式传递:
HTTP Header(HTTP请求头):Authorization:xxxxxxxx
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
}