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	参数错误
30001	token过期
40300	权限不足
40000	非法请求
50000	服务器内部错误

---

1. 登录认证

用户登录

• URL路径：/user/login

• 方法：POST

• 请求参数：

  参数	值类型	可空	说明
  userName	string	false	用户登录名，非空
  password	string	false	用户登录密码，非空，其值为明文密码两次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	用户已被封禁
  40305	上级管理员未认证该用户

---

用户注册（公共）

用户注册可由管理员手动创建，也可以由用户自行注册，但是需要提供管理员名称，并且由管理员确认信息后才能使用

在系统中首次注册的用户即为管理员，管理员注册后普通用户必须要提供上级管理员才能注册

• URL路径：/user/register

• 方法：POST

• 请求参数：

  参数	值类型	可空	说明
  userName	string	false	用户登录名，非空
  password	string	false	用户登录密码，非空，其值为明文密码两次sha256加密
  superior	string	true	上级管理员用户名

  例如：

  {
      "userName": "admin",
      "password": "e723fb2ff93afb010960ac20c05439f1cdd1ecbb533947e7de9f43656a612052",
      "superior": "lensfrex"
  }
  

• 返回数据

  参数	值类型	说明
  uid	string	用户对应的uid

  例如：

  {
      "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，必须提供

  例如：

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

---

3. 用户管理相关

这部分的的大部分接口只能由管理员调用使用

添加用户

• URL路径：/user/admin/add

• 方法：POST

• 请求参数：

  参数	值类型	可空	说明
  userName	string	false	用户登录名，非空
  password	string	false	用户登录密码，非空，其值为明文密码两次sha256加密
  role	int	true	用户角色
  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	权限不足
  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}

• 方法：POST

• 请求参数：

  参数	值类型	可空	说明
  uid	string(url)	false	欲修改状态的用户uid
  status	int	false	修改状态，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	权限不足

---

管理员获取待审批注册用户

• 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)	申请时间

  例如：

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

  例如：

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

• 返回数据

  data部分无返回数据

  例如：

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

• 错误信息

  code	错误
  40300	权限不足

---