16 KiB
DscapeAPI文档
这里是Dscape服务端的API文档。这里定义了该服务的接口以及调用方式。
若无特殊说明,请求均以json格式发送,参数字段对应为json的key,值为value
值类型中若有(header)
,则代表该字段应放在请求header中,而(url)
则代表该字段放置在URL请求路径中
这里并的接口并不完全遵照REST
注意,所有的请求都是在https下进行的
所有接口的Base URL:https://dscape.lensfrex.net/api/v1
目录
通用状态码
这里的状态码是所有接口都有可能会返回的状态码
code | 信息 |
---|---|
20000 | 成功 |
30000 | 非法请求 |
30001 | 参数错误 |
40000 | 权限不足 |
40001 | token过期 |
40002 | token无效 |
50000 | 服务器内部错误 |
0 | 接口未实现 |
登录认证
用户登录
-
URL路径:
/user/login
-
方法:
POST
-
请求参数:
参数 值类型 可空 说明 user_name string false 用户登录名,非空 password string false 用户登录密码,非空,其值为明文密码两次sha256加密 例如:
{ "user_name": "admin", "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052" }
-
返回数据
参数 值类型 说明 uid string 用户对应的uid role int 用户权限类型,0:普通用户,1:管理员 access_token string 本次登录得到的token,过期后应当用refresh_token重新获取 refresh_token string 刷新用的token,过期后应当重新登录 expired long access_token过期时间 例如:(token为精简过的jwt)
{ "code": 20000, "msg": "success", "data": { "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0", "role": 0, "access_token": "eyJ0NiJ9.eyJ1aWQijEwOH0.3CHJSQH1cD24", "refresh_token": "eyJ0NiJ9.eyJ1aWQijEwOH0.3CHJSQH1cD24", "expired": 1658676108943 } }
-
错误信息
code 错误 60101 用户名或密码错误 60102 用户已被封禁 60103 上级管理员未认证该用户
用户注册(公共)
在系统中首次注册的用户即为管理员,管理员注册后普通用户必须要提供上级管理员提供的注册码才能注册
-
URL路径:
/user/register
-
方法:
POST
-
请求参数:
参数 值类型 可空 说明 user_name string false 用户登录名,非空 password string false 用户登录密码,非空,其值为明文密码两次sha256加密 invite_code string true 上级管理员发放的注册码 例如:
{ "user_name": "lensfrex", "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052", "invite_code": "asdf" }
-
返回数据
参数 值类型 说明 uid string 用户对应的uid 例如:
{ "code": 20000, "msg": "success", "data" : { "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0" } }
-
错误信息
code 错误 40300 权限不足 60201 用户已存在 60202 注册码不正确
管理员添加用户,详见添加用户
计算相关
请求计算
-
URL路径:
/compute/add
-
方法:
POST
-
请求参数:
参数 值类型 可空 说明 pid string false 患者数据id ctdna int false 患者ctDNA长度 cpg int false 患者甲基化位点数 token string(header) false 请求token,必须提供 例如:
{ "pid": "2333", "ctdna": "213", "cpg": "4" }
-
返回数据
参数 值类型 说明 id string 本次计算请求的任务id 例如:
{ "code": 20000, "msg": "success", "data" : { "id": "33168d5f3d8658f25ae17724d00b6fd0" } }
计算状态信息的获取,详见计算状态查询
-
错误信息
code 错误 40300 权限不足 40303 计算请求的ip已被封禁 40304 计算请求的用户已被封禁 40305 用户的计算配额到达上限
计算记录查询
-
URL路径:
/history/query/{uid}?offset={offset}&limit={limit}&page={page}
-
方法:
GET
-
请求参数:
参数 值类型 可空 说明 uid string(url) false 需要获取记录的用户uid offset int(url) false 分页数据偏移量 limit int(url) false 每页数据数量 page int(url) false 分页页码 token string(header) false 请求token,必须提供 例如,需要获取用户uid为
9a6d777c-997d-a7e5-35f4-8471b7582ac0
记录的第三页数据,每页10条数据:https://dscape.lensfrex.net/api/v1/history/query/9a6d777c-997d-a7e5-35f4-8471b7582ac0?offset=20&limit=10&page=3
-
返回数据
data部分以数组的形式返回
参数 值类型 可空 说明 id int 数据id pid int 患者id ctdna int 患者ctDNA长度 cpg int 患者甲基化位点数 hcc boolean 患者是否为HCC hcc_infer boolean 推算得出的HCC状态 time datetime(string) 时间 例如:
{ "code": 20000, "msg": "success", "data" : [ { "id": 64888, "pid": 2333, "ctdna": 209, "cpg": 5, "hcc": true, "hcc_infer": true, "time": "2022-07-10 08:00:00" }, { "id": 648888, "pid": 23333, "ctdna": 209, "cpg": 5, "hcc": true, "hcc_infer": true, "time": "2022-07-10 08:00:00" }, // ... ] }
-
错误信息
code 错误 40300 权限不足
计算记录删除
-
URL路径:
/history/delete/{rid}
-
方法:
DELETE
或GET
-
请求参数:
参数 值类型 可空 说明 rid int(url) false 欲删除的计算历史记录 token string(header) false 当前登录用户的token 例如,需要获取id为
1145
的记录:https://dscape.lensfrex.net/api/v1/history/delete/1145
-
返回数据
data部分无返回数据
例如:
{ "code": 20000, "msg": "success", "data" : null }
-
错误信息
code 错误 40300 权限不足
计算状态查询
-
URL路径:
/compute/status/{tid}
-
方法:
GET
-
请求参数:
参数 值类型 可空 说明 tid string false 计算任务的id token string(header) false 当前登录用户的token 例如:
https://dscape.lensfrex.net/api/v1/compute/status/33168d5f3d8658f25ae17724d00b6fd0
-
返回数据
参数 值类型 说明 id string 本次计算请求的任务id status int 计算状态,0:完成,1:计算中,3:排队中,4:已被终止或未被运行 例如:
{ "code": 20000, "msg": "success", "data" : { "id": "33168d5f3d8658f25ae17724d00b6fd0", "status": 0 } }
-
错误信息
code 错误 40300 权限不足
用户管理相关
这部分的的大部分接口只能由管理员调用使用
添加用户
-
URL路径:
/user/admin/add
-
方法:
POST
-
请求参数:
参数 值类型 可空 说明 user_name string false 用户登录名,非空 password string false 用户登录密码,非空,其值为明文密码两次sha256加密 role int true 用户角色 token string(header) 管理员的access_token 例如:
{ "user_name": "admin", "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052", "role": 0 }
-
返回数据
字段 值类型 说明 uid string 用户对应的uid role int 用户权限类型,0:普通用户,1:管理员 例如:
{ "code": 20000, "msg": "success", "data" : { "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0", "role": 0 } }
-
错误信息
code 错误 40300 权限不足 20001 用户已存在
修改密码
修改密码只能由用户自己修改,或者管理员重置密码
-
URL路径:
/user/modifyPassword/{uid}
-
方法:
POST
-
请求参数:
参数 值类型 可空 说明 uid string(url) false 欲修改密码的用户uid old_password string true 原始密码,其值为明文密码两次sha256加密,若不提供,则token拥有者应当为管理员 new_password string false 新密码,其值为明文密码两次sha256加密 token string(header) false 当前对应用户的uid 例如:
{ "old_password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052", "new_password": "384fde3636e6e01e0194d2976d8f26410af3e846e573379cb1a09e2f0752d8cc" }
-
返回数据
data部分无返回数据
例如:
{ "code": 20000, "msg": "success", "data" : null }
-
错误信息
code 错误 40300 权限不足
封禁、删除用户
-
URL路径:
/user/admin/modifyStatus/{uid}?status={status}
-
方法:
POST
-
请求参数:
参数 值类型 可空 说明 uid string(url) false 欲修改状态的用户uid status int(url) false 修改状态,0:正常;1:彻底封禁(无法登录);2:注销(销号);3:计算封禁 token string(header) 当前对应用户的uid -
返回数据
data部分无返回数据
例如:
{ "code": 20000, "msg": "success", "data" : null }
-
错误信息
code 错误 40300 权限不足
管理员发放注册码
-
URL路径:
/user/admin/inviteCode?expired={expired}&count={count}
-
方法:
GET
-
请求参数:
参数 值类型 可空 说明 expired long(url) false 过期时间,留空或设为0表示不过期,以时间戳为格式 count int(url) false 获取数量,留空只获取一条,每位管理员最大可申请1024条(有效的) -
返回数据
data部分以数组的形式返回
参数 值类型 可空 说明 例如:
{ "code": 20000, "msg": "success", "data" : [ "asdf", "zxcv", "qwer" // ... ] }
-
错误信息
code 错误 40300 权限不足 60401 申请数量超过上限