193 lines
5.4 KiB
Markdown
193 lines
5.4 KiB
Markdown
# 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）。
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"msg": "username error"
|
||
}
|
||
```
|
||
|
||
一般数据类型包含`ID`字段，类型为整数。DELETE方法可用此字段表示将要删除的对象。删除一个镜像的请求如下命令所示。
|
||
|
||
```bash
|
||
curl -X DELETE https://ms.educg.net/admin/image?ID=1
|
||
```
|
||
|
||
### 资源查询请求
|
||
|
||
对单个资源查询的方式与删除类似，可使用该数据结构中的某些字段对数据进行查询，返回结果为Json格式。
|
||
|
||
同时对该类型的多个资源进行查询时，URL一般为该资源类型的复数形式，如镜像的查询URL为`image`
|
||
，那么同时获得多个镜像的查询的URL为`images`。特殊情况另行说明。
|
||
对多个数据进行查询时，URL中除了必要的过滤条件外，还可包含分页参数`page`和`pageSize`，均为整数类型。返回结果中`data`
|
||
字段为查询结果数据，`page`、`pageCount`和`pageSize`用于控制分页。
|
||
|
||
```json
|
||
{
|
||
"page": 1,
|
||
"pageCount": 100,
|
||
"pageSize": 2,
|
||
"data": [
|
||
{
|
||
"ID": 2,
|
||
"Other fields": "Other Values"
|
||
},
|
||
{
|
||
"ID": 3
|
||
}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
### 数据结构
|
||
数据结构使用Golang语言格式进行定义，其中`gorm.Model`为公用字段，定义如下：
|
||
```go
|
||
type Model struct {
|
||
ID uint `gorm:"primarykey"`
|
||
CreatedAt time.Time
|
||
UpdatedAt time.Time
|
||
DeletedAt DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
数据结构中包含的Comment字段为该数据的简单描述，Doc字段为该数据的详细文档，文档应支持Markdown格式保存和渲染。
|
||
在所有创建对象的请求（POST）中，ID字段将被忽略，创建成功后自动分配ID。
|
||
|
||
## 镜像管理
|
||
|
||
数据结构：
|
||
|
||
```go
|
||
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 # 查询所有公开镜像
|
||
|
||
## 数据集管理
|
||
|
||
训练数据，数据结构：
|
||
```go
|
||
type DataModel struct {
|
||
gorm.Model
|
||
Type string
|
||
Name string
|
||
Comment string
|
||
Doc string
|
||
UserName 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
|
||
|
||
## 项目管理
|
||
|
||
数据结构
|
||
```go
|
||
type ProjectModel struct {
|
||
gorm.Model
|
||
ProjectName string
|
||
UserName string
|
||
GroupName string
|
||
Type string
|
||
Comment string
|
||
Doc string
|
||
IsPublic bool
|
||
|
||
Image ImageModel
|
||
TrainData []*ProjectTrainDataModel `gorm:"foreignKey:ProjectID"`
|
||
|
||
|
||
UserPath string // 用户目录挂载位置
|
||
CodePath string // 代码目录挂载位置
|
||
ModelPath string // 模型目录挂载位置
|
||
|
||
Running bool `gorm:"-:all"`
|
||
}
|
||
|
||
|
||
type ProjectTrainDataModel struct {
|
||
BaseModel[ProjectTrainDataModel]
|
||
Project *ProjectModel
|
||
Data *DataModel
|
||
MountPath string
|
||
}
|
||
```
|
||
|
||
其中`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
|
||
|
||
## 运行项目 （尚未实现）
|
||
|
||
数据结构
|
||
```go
|
||
type RunningProject struct {
|
||
ID int
|
||
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为容器服务客户端连接地址，可通过本地客户端提供更多功能。
|
||
|
||
CURD:
|
||
+ POST：/running_project
|
||
+ DELETE: /running_project?ID=1
|
||
+ GET /running_projects?UserName=cg_wmj
|