wmj-test/API.md

API 文档

总体设计

基本HTTP请求

本系统后端API设计遵循RESTful规范，对于一般数据类型的增删改查使用同一URL下的POST、DELETE、PUT和GET方法进行访问。 对于POST和PUT方法，待传输数据放在请求体中，以Json格式进行传输。DELETE和GET方法使用URL参数传递必要数据。POST为上传新数据，使用POST时数据中ID字段将被忽略。

后端返回数据也全部为Json格式，使用HTTP状态码标识请求状态。当状态码为200时可以认为该请求成功达到了预期的结果。若请求失败，则状态码不为200，并且返回数据中包含msg 字段对发生的错误进行了简要说明。

一次失败的请求返回数据如下所示，其状态码为401（StatusUnauthorized）。

{
  "ok": false,
  "msg": "username error"
}

一般数据类型包含ID字段，类型为整数。DELETE方法可用此字段表示将要删除的对象。删除一个镜像的请求如下命令所示。

curl -X DELETE https://ms.educg.net/admin/image?ID=1

资源查询请求

对单个资源查询的方式与删除类似，可使用该数据结构中的某些字段对数据进行查询，返回结果为Json格式。

同时对该类型的多个资源进行查询时，URL一般为该资源类型的复数形式，如镜像的查询URL为image ，那么同时获得多个镜像的查询的URL为images。特殊情况另行说明。 对多个数据进行查询时，URL中除了必要的过滤条件外，还可包含分页参数page和pageSize，均为整数类型。返回结果中data 字段为查询结果数据，page、pageCount和pageSize用于控制分页。

{
  "page": 1,
  "pageCount": 100,
  "pageSize": 2,
  "data": [
    {
      "ID": 2,
      "Other fields": "Other Values"
    },
    {
      "ID": 3
    }
  ]
}

数据结构

数据结构使用Golang语言格式进行定义，其中gorm.Model为公用字段，定义如下：

type Model struct {
    ID        uint `gorm:"primarykey"`
    CreatedAt time.Time
    UpdatedAt time.Time
    DeletedAt DeletedAt `gorm:"index"`
}

数据结构中包含的Comment字段为该数据的简单描述，Doc字段为该数据的详细文档，文档应支持Markdown格式保存和渲染。

镜像管理

数据结构：

type ImageModel struct {
    gorm.Model
    Name        string
    Image       string
    Comment     string
    Command     string
    Env         string
    Port        string
    UserName    string
    IsPublished bool
    Doc         string
}

CURD:

• POST：/image
• PUT: /image
• DELETE: /image?ID=1
• GET /images?UserName=cg_wmj # 查询某用户的镜像
• GET /images?IsPublish=1 # 查询所有公开镜像

数据集管理 （尚未实现）

训练数据，数据结构：

type DataModel struct {
    gorm.Model
    Type        string
    Name        string
    Comment     string
    Doc         string
    UserName    string
    Password    string
    AccessInfo  string
    IsPublished bool
}

其中Type字段为数据集的类型，表示该数据集的访问方式，目前仅支持Type=="dir"访问目录格式数据，后续可能支持mysql等数据库。 本系统中，对本地文件的访问使用Webdav协议。 AccessInfo字段为该数据集的访问方式，在Type=="dir"时为该目录的路径。 例如某数据集对象中，AccessInfo=='/some/data/dir/'，同时文件服务器地址为https://ms.educg.net/files/ ，那么通过WebDav协议访问https://ms.educg.net/files/some/data/dir/ 即可访问该目录。

CURD:

• POST：/data
• PUT: /data
• DELETE: /data?ID=1
• GET /data?UserName=cg_wmj
• GET /data?IsPublish=1

项目管理 （尚未实现）

数据结构

type ProjectModel struct {
	gorm.Model
	ProjectName string
	UserName    string
	GroupName   string
	Type        string
	Comment     string
	Doc         string
	IsPublic    bool

	ImageID   int
	Image     ImageModel
	TrainData []*DataModel `gorm:"many2many:projects_data"`


	UserPath string    // 用户目录挂载位置
    CodePath string    // 代码目录挂载位置
    ModelPath string   // 模型目录挂载位置

	Running  bool   `gorm:"-:all"`
}

其中Type字段为项目的类型，可选值为jupyter、jupyterlab、jupyternotebook、novnc、vscode、http。

在创建或更新项目时，TrainData字段应该为DataModel结构的列表，其中每一个DataModel仅有ID即可。

CURD:

• POST：/project
• PUT: /project
• DELETE: /project?ID=1
• GET /projects?UserName=cg_wmj
• GET /projects?IsPublish=1

运行项目 （尚未实现）

数据结构

type RunningProject struct {
    Project   *ProjectModel
    StartTime *time.Time
    UserName  string
    Nodes     int
    Cpus      int
    Memory    int
    Gpus      int
    GpuMemory int
    URL       string
    ControlURL string
}

运行一个项目，前端发送POST请求时URL可留空，若该项目成功启动，则POST的返回内容中将包含正确的URL。 通过此URL即可访问项目服务。ControlURL为容器服务客户端连接地址，可通过本地客户端提供更多功能。

此数据结构中没有ID字段，删除时使用其对应的ProjectModel的ID。

CURD:

• POST：/running_project
• DELETE: /running_project?ProjectID=1
• GET /running_projects?UserName=cg_wmj