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.
16 Commits
2 Branches
0 Tags
1.3 MiB
 
 
Tag: Branch: Tree: 5bbf9113c8
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '5bbf9113c8'
${ noResults }
dscape-server/API-Document.md

547 lines
16 KiB
Raw Blame History

# DscapeAPI文档
这里是Dscape服务端的API文档。这里定义了该服务的接口以及调用方式。
若无特殊说明，请求均以json格式发送，参数字段对应为json的key，值为value
值类型中若有`(header)`，则代表该字段应放在请求header中，而`(url)`则代表该字段放置在URL请求路径中
这里并的接口并不完全遵照REST
注意，所有的请求都是在https下进行的
所有接口的Base URL：`https://dscape.lensfrex.net/api/v1`
---
# 目录
- [DscapeAPI文档](#dscapeapi文档)
- [目录](#目录)
- [通用状态码](#通用状态码)
- [登录认证](#登录认证)
- [用户登录](#用户登录)
- [用户注册（公共）](#用户注册公共)
- [计算相关](#计算相关)
- [请求计算](#请求计算)
- [计算记录查询](#计算记录查询)
- [计算记录删除](#计算记录删除)
- [计算状态查询](#计算状态查询)
- [用户管理相关](#用户管理相关)
- [添加用户](#添加用户)
- [修改密码](#修改密码)
- [封禁、删除用户](#封禁删除用户)
- [管理员发放注册码](#管理员发放注册码)
---
## 通用状态码
这里的状态码是所有接口都有可能会返回的状态码
| code | 信息 |
| ----- | -------------- |
| 20000 | 成功 |
| 30000 | 非法请求 |
| 30001 | 参数错误 |
| 40000 | 权限不足 |
| 40001 | token过期 |
| 40002 | token无效 |
| 50000 | 服务器内部错误 |
| 0 | 接口未实现 |
---
## 登录认证
### 用户登录
- URL路径：`/user/login`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --------- | ------ | ----- | ------------------------------------------------ |
| user_name | string | false | 用户登录名，非空 |
| password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
例如：
``` json
{
"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)
``` 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 | 错误 |
| ----- | ---------------------- |
| 60101 | 用户名或密码错误 |
| 60102 | 用户已被封禁 |
| 60103 | 上级管理员未认证该用户 |
---
### 用户注册（公共）
> 在系统中首次注册的用户即为管理员，管理员注册后普通用户必须要提供上级管理员提供的注册码才能注册
- URL路径：`/user/register`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| ----------- | ------ | ----- | ------------------------------------------------ |
| user_name | string | false | 用户登录名，非空 |
| password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
| invite_code | string | true | 上级管理员发放的注册码 |
例如：
``` json
{
"user_name": "lensfrex",
"password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
"invite_code": "asdf"
}
```
- 返回数据
| 参数 | 值类型 | 说明 |
| ---- | ------ | ------------- |
| uid | string | 用户对应的uid |
例如：
``` json
{
"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，必须提供 |
例如：
``` 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 | 权限不足 |
---
## 用户管理相关
> 这部分的的大部分接口只能由管理员调用使用
### 添加用户
- URL路径：`/user/admin/add`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| --------- | -------------- | -------------------- | ------------------------------------------------ |
| user_name | string | false | 用户登录名，非空 |
| password | string | false | 用户登录密码，非空，其值为明文密码两次sha256加密 |
| role | int | true | 用户角色 |
| token | string(header) | 管理员的access_token |
例如：
``` json
{
"user_name": "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}?status={status}`
- 方法：`POST`
- 请求参数：
| 参数 | 值类型 | 可空 | 说明 |
| ------ | -------------- | ----------------- | ------------------------------------------------------------------------ |
| uid | string(url) | false | 欲修改状态的用户uid |
| status | int(url) | false | 修改状态，0：正常；1：彻底封禁（无法登录）；2：注销（销号）；3：计算封禁 |
| token | string(header) | 当前对应用户的uid |
- 返回数据
> data部分无返回数据
例如：
``` json
{
"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部分以数组的形式返回
| 参数 | 值类型 | 可空 | 说明 |
| ---- | ---------------- | ------------------ | ---- |
例如：
``` json
{
"code": 20000,
"msg": "success",
"data" : [
"asdf",
"zxcv",
"qwer"
// ...
]
}
```
- 错误信息
| code | 错误 |
| ----- | -------- |
| 40300 | 权限不足 |
| 60401 | 申请数量超过上限 |
---