lensfrex
/
dscape-server
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
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.
6 Commits
2 Branches
0 Tags
1.3 MiB
 
 
Tag: Branch: Tree: ee0dd0f05b
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ee0dd0f05b'
${ noResults }
dscape-server/API-Document.md

597 lines
14 KiB
Raw Blame History

# 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 | 参数错误 |
| 30001 | token过期 |
| 40300 | 权限不足 |
| 40000 | 非法请求 |
| 50000 | 服务器内部错误 |
---
## 1. 登录认证
### 用户登录
- URL路径：`/user/login`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| userName | string | false |用户登录名，非空 |
| password | string | false |用户登录密码，非空，其值为明文密码两次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 | 用户已被封禁 |
| 40305 | 上级管理员未认证该用户 |
---
### 用户注册（公共）
> 用户注册可由管理员手动创建，也可以由用户自行注册，但是需要提供管理员名称，并且由管理员确认信息后才能使用
>
> 在系统中首次注册的用户即为管理员，管理员注册后普通用户必须要提供上级管理员才能注册
- URL路径：`/user/register`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| userName | string | false | 用户登录名，非空 |
| password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
| superior | string | true | 上级管理员用户名 |
例如：
``` json
{
"userName": "admin",
"password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
"superior": "lensfrex"
}
```
- 返回数据
| 参数 | 值类型 | 说明 |
| --- | --- | --- |
| uid | string | 用户对应的uid |
例如：
``` json
{
"code": 20000,
"msg": "success",
"data" : {
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0"
}
}
```
- 错误信息
| code | 错误 |
| --- | --- |
| 40300 | 权限不足 |
| 20001 | 用户已存在 |
> 管理员添加用户，详见[添加用户](#添加用户)
---
## 2. 计算相关
### 请求计算
- URL路径：`/compute/add`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| pid | string | false | 患者数据id |
| ctdna | int | false | 患者ctDNA长度 |
| cpg | int | false | 患者甲基化位点数 |
| token | string(header) | false |请求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) | 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) | 时间 |
例如：
``` 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) | false | 欲删除的计算历史记录 |
| token | string(header) | false |当前登录用户的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 | 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：已被终止或未被运行 |
例如：
``` json
{
"code": 20000,
"msg": "success",
"data" : {
"id": "33168d5f3d8658f25ae17724d00b6fd0",
"status": 0
}
}
```
- 错误信息
| code | 错误 |
| --- | --- |
| 40300 | 权限不足 |
---
## 3. 用户管理相关
> 这部分的的大部分接口只能由管理员调用使用
### 添加用户
- URL路径：`/user/admin/add`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| userName | string | false | 用户登录名，非空 |
| password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
| role | int | true | 用户角色 |
| 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 | 权限不足 |
| 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 |
例如：
``` json
{
"old_password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
"new_password": "384fde3636e6e01e0194d2976d8f26410af3e846e573379cb1a09e2f0752d8cc"
}
```
- 返回数据
> data部分无返回数据
例如：
``` json
{
"code": 20000,
"msg": "success",
"data" : null
}
```
- 错误信息
| code | 错误 |
| --- | --- |
| 40300 | 权限不足 |
---
### 封禁、删除用户
- URL路径：`/user/admin/modifyStatus/{uid}`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| uid | string(url) | false | 欲修改状态的用户uid |
| status | int | false |修改状态，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 | 权限不足 |
---
### 管理员获取待审批注册用户
- URL路径：`/user/admin/application/list?offset={offset}&limit={limit}&page={page}`
- 方法：`GET`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| offset | int(url) | false | 分页数据偏移量 |
| limit | int(url) | false | 每页数据数量 |
| page | int(url) | false | 分页页码 |
| token | string(header) | false | 请求token，必须提供 |
例如，需要第三页数据，每页10条数据：
```
https://dscape.lensfrex.net/api/v1/user/admin/apply?offset=20&limit=10&page=3
```
- 返回数据
> data部分以数组的形式返回
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| id | int | 审批记录id |
| uid | string | 待审批用户uid |
| name | string | 待审批用户名 |
| ip | string | 用户发送审批时的ip |
| time | datetime(string) | 申请时间 |
例如：
``` json
{
"code": 20000,
"msg": "success",
"data" : [
{
"id": 64888,
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
"name": "lensfrex2",
"ip": "127.0.0.1",
"time": "2022-07-10 08:00:00"
},
{
"id": 64889,
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac1",
"name": "lensfrex2",
"ip": "127.0.0.1",
"time": "2022-07-10 08:00:00"
},
// ...
]
}
```
- 错误信息
| code | 错误 |
| --- | --- |
| 40300 | 权限不足 |
---
### 审核用户注册
- URL路径：`/user/admin/application/deal/{uid}`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --- | --- | --- | --- |
| uid | string(url) | false | 处理的用户uid |
| idea | boolean | false | 处理意见，true：通过；false：拒绝 |
| token | string(header) | 当前对应用户的uid |
例如：
``` json
{
"uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
"idea": true
}
```
- 返回数据
> data部分无返回数据
例如：
``` json
{
"code": 20000,
"msg": "success",
"data" : null
}
```
- 错误信息
| code | 错误 |
| --- | --- |
| 40300 | 权限不足 |
---