You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
439 lines
10 KiB
439 lines
10 KiB
# Dscape Restful API文档
|
|
|
|
这里是Dscape服务端的API文档。这里定义了该服务的接口以及调用方式。
|
|
|
|
若无特殊说明，请求均以json格式发送，参数字段对应为json的key，值为value
|
|
|
|
值类型中若有`(header)`，则代表该字段应放在请求header中，而`(url)`则代表该字段放置在URL请求路径中
|
|
|
|
这里并的接口并不完全遵照REST
|
|
|
|
注意，所有的请求都是在https下进行的
|
|
|
|
所有接口的Base URL：`https://dscape.lensfrex.net/api/v1`
|
|
|
|
---
|
|
|
|
## 0. 通用信息（非http状态码）
|
|
|
|
| code | 信息 |
|
|
| --- | --- |
|
|
| 20000 | 成功 |
|
|
| 30000 | 参数错误
|
|
| 40300 | 权限不足 |
|
|
| 40000 | 非法请求 |
|
|
| 50000 | 服务器内部错误 |
|
|
|
|
---
|
|
|
|
## 1. 登录认证
|
|
|
|
### 用户登录
|
|
|
|
- URL路径：`/user/login`
|
|
- 方法：`POST`
|
|
|
|
- 请求参数：
|
|
|
|
| 参数 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| userName | string | 用户登录名，非空 |
|
|
| password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"userName": "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)
|
|
``` json
|
|
{
|
|
"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 | 错误 |
|
|
| --- | --- |
|
|
| 40301 | 用户名或密码错误 |
|
|
| 40302 | 用户已被封禁 |
|
|
|
|
---
|
|
|
|
### 用户注册
|
|
|
|
> 普通用户并不提供注册功能，只能由管理员添加
|
|
>
|
|
> 在系统中首次注册的用户即为管理员，管理员注册后注册接口将不会处理任何非管理员请求，只能由管理员用户请求
|
|
|
|
- URL路径：`/user/register`
|
|
- 方法：`POST`
|
|
|
|
- 请求参数：
|
|
|
|
| 参数 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| userName | string | 用户登录名，非空 |
|
|
| password | string | 用户登录密码，非空，其值为明文密码两次sha256加密 |
|
|
| role | int | 用户角色，该选项只能由管理员使用，其他用户提供不生效 |
|
|
| token | string(header) | 管理员的access_token，如不提供且已经有初始管理员则会导致请求失败（权限不足） |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"userName": "admin",
|
|
"password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
|
|
"role": 0
|
|
}
|
|
```
|
|
|
|
- 返回数据
|
|
|
|
| 字段 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| uid | string | 用户对应的uid |
|
|
| role | int | 用户权限类型，0：普通用户，1：管理员 |
|
|
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"code": 20000,
|
|
"msg": "success",
|
|
"data" : {
|
|
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
|
|
"role": 0
|
|
}
|
|
}
|
|
```
|
|
- 错误信息
|
|
|
|
| code | 错误 |
|
|
| --- | --- |
|
|
| 40300 | 权限不足 |
|
|
|
|
---
|
|
|
|
## 2. 计算相关
|
|
|
|
### 请求计算
|
|
|
|
- URL路径：`/compute/add`
|
|
- 方法：`POST`
|
|
|
|
- 请求参数：
|
|
|
|
| 参数 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| pid | string | 患者数据id |
|
|
| ctdna | int | 患者ctDNA长度 |
|
|
| cpg | int | 患者甲基化位点数 |
|
|
| token | string(header) | 请求token，必须提供 |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"pid": "2333",
|
|
"ctdna": "213",
|
|
"cpg": "4"
|
|
}
|
|
```
|
|
|
|
- 返回数据
|
|
|
|
| 字段 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| id | string | 本次计算请求的任务id |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"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) | 需要获取记录的用户uid |
|
|
| offset | int(url) | 分页数据偏移量 |
|
|
| limit | int(url) | 每页数据数量 |
|
|
| page | int(url) | 分页页码 |
|
|
| token | string(header) | 请求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) | 时间 |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"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) | 欲删除的计算历史记录 |
|
|
| token | string(header) | 当前登录用户的token |
|
|
|
|
例如，需要获取id为`1145`的记录：
|
|
```
|
|
https://dscape.lensfrex.net/api/v1/history/delete/1145
|
|
```
|
|
|
|
- 返回数据
|
|
|
|
> data部分无返回数据
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"code": 20000,
|
|
"msg": "success",
|
|
"data" : null
|
|
}
|
|
```
|
|
|
|
|
|
- 错误信息
|
|
|
|
| code | 错误 |
|
|
| --- | --- |
|
|
| 40300 | 权限不足 |
|
|
|
|
---
|
|
|
|
### 计算状态查询
|
|
|
|
- URL路径：`/compute/status/{tid}`
|
|
- 方法：`GET`
|
|
|
|
- 请求参数：
|
|
|
|
| 参数 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| tid | string | 计算任务的id |
|
|
| token | string(header) | 当前登录用户的token |
|
|
|
|
例如：
|
|
```
|
|
https://dscape.lensfrex.net/api/v1/compute/status/33168d5f3d8658f25ae17724d00b6fd0
|
|
```
|
|
|
|
- 返回数据
|
|
|
|
| 字段 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| id | string | 本次计算请求的任务id |
|
|
| status | int | 计算状态，0：完成，1：计算中，3：排队中，4：已被终止或未被运行 |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"code": 20000,
|
|
"msg": "success",
|
|
"data" : {
|
|
"id": "33168d5f3d8658f25ae17724d00b6fd0",
|
|
"status": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
- 错误信息
|
|
|
|
| code | 错误 |
|
|
| --- | --- |
|
|
| 40300 | 权限不足 |
|
|
|
|
---
|
|
|
|
## 3. 用户管理相关
|
|
|
|
### 添加用户
|
|
|
|
> 该项与注册接口相同
|
|
|
|
---
|
|
|
|
### 修改密码
|
|
|
|
> 修改密码只能由用户自己修改，或者管理员重置密码
|
|
|
|
- URL路径：`/user/modifyPassword/{uid}`
|
|
- 方法：`POST`
|
|
|
|
- 请求参数：
|
|
|
|
| 参数 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| uid | string(url) | 欲修改密码的用户uid |
|
|
| old_password | string | 原始密码，其值为明文密码两次sha256加密，若不提供，则token拥有者应当为管理员 |
|
|
| new_password | string | 新密码，其值为明文密码两次sha256加密 |
|
|
| token | string(header) | 当前对应用户的uid |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"old_password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
|
|
"new_password": "384fde3636e6e01e0194d2976d8f26410af3e846e573379cb1a09e2f0752d8cc"
|
|
}
|
|
```
|
|
|
|
- 返回数据
|
|
|
|
> data部分无返回数据
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"code": 20000,
|
|
"msg": "success",
|
|
"data" : null
|
|
}
|
|
```
|
|
|
|
- 错误信息
|
|
|
|
| code | 错误 |
|
|
| --- | --- |
|
|
| 40300 | 权限不足 |
|
|
|
|
---
|
|
|
|
### 封禁、删除用户
|
|
|
|
- URL路径：`/user/modifyStatus/{uid}`
|
|
- 方法：`POST`
|
|
|
|
- 请求参数：
|
|
|
|
| 参数 | 值类型 | 说明 |
|
|
| --- | --- | --- |
|
|
| uid | string(url) | 欲修的用户uid |
|
|
| status | int | 修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
|
|
| token | string(header) | 当前对应用户的uid |
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
|
|
"new_password": 1
|
|
}
|
|
```
|
|
|
|
- 返回数据
|
|
|
|
> data部分无返回数据
|
|
|
|
例如：
|
|
``` json
|
|
{
|
|
"code": 20000,
|
|
"msg": "success",
|
|
"data" : null
|
|
}
|
|
```
|
|
|
|
- 错误信息
|
|
|
|
| code | 错误 |
|
|
| --- | --- |
|
|
| 40300 | 权限不足 | |