dscape-server/API-Document.md

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加密

  例如：

  {
      "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)

  {
      "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，如不提供且已经有初始管理员则会导致请求失败（权限不足）

  例如：

  {
      "userName": "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	权限不足

---

2. 计算相关

请求计算

• URL路径：/compute/add

• 方法：POST

• 请求参数：

  参数	值类型	说明
  pid	string	患者数据id
  ctdna	int	患者ctDNA长度
  cpg	int	患者甲基化位点数
  token	string(header)	请求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)	需要获取记录的用户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)	时间

  例如：

  {
      "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部分无返回数据

  例如：

  {
      "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：已被终止或未被运行

  例如：

  {
      "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

  例如：

  {
      "old_password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
      "new_password": "384fde3636e6e01e0194d2976d8f26410af3e846e573379cb1a09e2f0752d8cc"
  }
  

• 返回数据

  data部分无返回数据

  例如：

  {
      "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

  例如：

  {
      "uid": "9a6d777c-997d-a7e5-35f4-8471b7582ac0",
      "new_password": 1
  }
  

• 返回数据

  data部分无返回数据

  例如：

  {
      "code": 20000,
      "msg": "success",
      "data" : null
  }
  

• 错误信息

  code	错误
  40300	权限不足