# REST API

Rest API 设计用于作业、配置和集群管理。

### 分布式加载

提前将UFS数据加载到worker中缓存，避免冷读对用户产生性能影响。

#### 提交或恢复加载作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| POST   | /api/v1/load | 无      | Content-Type: application/json |

**参数**

| **名称**    | **类型** | **必填** | **描述**              | **示例**                                                                       |
| --------- | ------ | ------ | ------------------- | ---------------------------------------------------------------------------- |
| `index`   | string | 否      | ufs 上的索引文件路径（必须已挂载） | '{"index": s3://bucket/key}'                                                 |
| `paths`   | string | 否      | 要加载的 ufs 路径列表       | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"]}'                       |
| `alias`   | string | 否      | 和paths组合使用，供后续状态查询  | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}' |
| `options` | object | 否      | 配置加载作业的选项           | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                     |

其中，`index`和`paths`二选一. `paths`可以指定`alias`，否则内部随机生成alias返回用户。

可以使用 `options` 来配置加载作业的选项。可选字段有：

| **名称**             | **类型** | **必填** | **描述**                           |
| ------------------ | ------ | ------ | -------------------------------- |
| `batchSize`        | int    | 否      | worker从 ufs 加载数据的批处理大小           |
| `replicas`         | int    | 否      | 加载文件副本数，默认值config中设置对应路径副本或1     |
| `skipIfExists`     | bool   | 否      | 如果文件已存在，则跳过加载过程.                 |
| `loadPolicy`       | enum   | 否      | 目前仅支持 IF\_CHANGED。如果文件已更改，则更新文件。 |
| `loadMetadataOnly` | bool   | 否      | 仅加载文件元数据。                        |

**示例**

一个 JSON 请求负载示例如下：

```json
{
  "paths": [
    "s3://my-bucket/dir/to/path"
  ],
  "options": {
    "batchSize": 1,
    "replicas": 1,
    "loadMetadataOnly": true,
    "loadPolicy": "IF_CHANGED"
  }
}
```

正常返回示例：json格式

```
{
  "target":"job-95e8a01f-d519-4c1a-8311-26714f4db623",
  "id":"1cf35e69-b6e6-4807-8aae-588e0e994277"
}
```

**错误码**

| **http状态码** | **错误码**               | **描述**                 |
| ----------- | --------------------- | ---------------------- |
| 200         | OK                    | 操作成功                   |
| 400         | Bad Request           | 请求没有正文或缺少必需字段          |
| 409         | Conflict              | 已经存在相同的job被调度，拒绝新任务的提交 |
| 500         | Internal Server Error | 意外错误                   |

#### 获取加载作业进度

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/load | 有      | 无         |

**参数：**

| **名称**       | **类型** | **必填** | **描述**                  | **示例**                                                                           |
| ------------ | ------ | ------ | ----------------------- | -------------------------------------------------------------------------------- |
| `target`     | string | 是      | 提交job时返回字段信息            | target=job-95e8a01f-d519-4c1a-8311-26714f4db623                                  |
| `fileList`   | bool   | 否      | 获取加载文件列表                | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true                   |
| `fileStatus` | string | 否      | 文件列表类型\[TOTAL\|FAILURE] | target=job-95e8a01f-d519-4c1a-8311-26714f4db623\&fileList=true\&fileStatus=TOTAL |

注：3.7查询参数依然兼容, 例如:`alias`,`index`

**示例** 获取任务执行状态正常返回示例：json格式

```
{
    "id": "043cc6c2-b456-4d57-a807-a8c86256d8f2",
    "startTime": "2026-01-16T16:35:35.32+08:00",
    "endTime": "2026-01-16T16:35:42.149+08:00",
    "jobState": "SUCCEEDED",
    "timeElapsedMilliseconds": 6829,
    "paths": [
        "s3://test/index"
    ],
    "alias": "job-e7cc61f3-fdd5-45fe-a11b-e8f92f0c6d05",
    "batchSize": 200,
    "loadedBytes": 127,
    "totalBytes": 127,
    "loadedNonEmptyFiles": 1,
    "scannedFiles": 1,
    "replicas": "ALL"
}
```

获取任务列表正常返回示例：json格式

```
[
    {
        "path": "s3://test/index",
        "size": 0,
        "mTime": 0
    },
    {
        "path": "s3://test/index-copy",
        "size": 0,
        "mTime": 0
    }
]
```

**错误码**

| **http状态码** | **错误码**               | **描述** |
| ----------- | --------------------- | ------ |
| 200         | OK                    | 操作成功   |
| 404         | Not Found             | 任务不存在  |
| 500         | Internal Server Error | 意外错误   |

#### 停止加载作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| DELETE | /api/v1/load | 无      | Content-Type: application/json |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                                |
| -------- | ------ | ------ | ------------ | ----------------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

注：3.7停止参数依然兼容， 例如:`alias`,`index`

**错误码**

| **http状态码** | **错误码**     | **描述**        |
| ----------- | ----------- | ------------- |
| 200         | OK          | 操作成功          |
| 400         | Bad Request | 请求没有正文或缺少必需字段 |
| 404         | Not Found   | 加载作业不存在       |
| 410         | Gone        | 加载作业已完成       |

#### 列举加载作业列表

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/load | 有      | 无         |

**参数：**

| **名称**    | **类型** | **必填** | **描述**                                 |
| --------- | ------ | ------ | -------------------------------------- |
| `state`   | enum   | 否      | 作业状态\[RUNNING\|SUCCEEDED\|FAILED\|ALL] |
| `lastKey` | string | 否      | 从当前作键开始列举作业                            |
| `count`   | int    | 否      | 预期列出的作业数量                              |

注：没有参数将会列举所有job

**错误码**

| **http状态码** | **错误码** | **描述** |
| ----------- | ------- | ------ |
| 200         | OK      | 操作成功   |

**响应** 一个正常列举的响应：json格式

```
{
    "results": [
        {
            "id": "53b3123d-a042-4eb1-90e5-73798b963b04",
            "startTime": "2026-01-17T08:22:52.787+08:00",
            "endTime": "2026-01-17T08:22:57.289+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4502,
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-1cfb048e-7ca7-48d3-8dd3-aa2ed8472176",
            "batchSize": 200,
            "loadedBytes": 127,
            "totalBytes": 127,
            "loadedNonEmptyFiles": 1,
            "scannedFiles": 1,
            "replicas": "ALL"
        },
        {
            "id": "89e288cf-480a-40df-a45b-91c3e08cb138",
            "startTime": "2026-01-17T08:22:54.117+08:00",
            "endTime": "1970-01-01T08:00:00+08:00",
            "jobState": "RUNNING",
            "runningStage": "LOADING",
            "paths": [
                "s3://tidas-alluxio-test/index"
            ],
            "alias": "job-9869111f-99f3-4ee4-9dbe-6c0204b96aec",
            "batchSize": 200,
            "replicas": "ALL"
        }
    ]
}
```

### 释放缓存

将worker缓存数据清理，释放缓存存储空间

#### 提交或恢复释放作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| POST   | /api/v1/free | 无      | Content-Type: application/json |

**参数**

| **名称**    | **类型** | **必填** | **描述**              | **示例**                                                                       |
| --------- | ------ | ------ | ------------------- | ---------------------------------------------------------------------------- |
| `index`   | string | 否      | ufs 上的索引文件路径（必须已挂载） | '{"index": s3://bucket/key}'                                                 |
| `paths`   | string | 否      | 要释放的 ufs 路径列表       | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"]}'                       |
| `alias`   | string | 否      | 和paths组合使用，供后续状态查询  | '{"paths": \["s3://bucket/key1", "s3://bucket/key2"], "alias": "database1"}' |
| `options` | object | 否      | 配置加载作业的选项           | '{"index": s3://bucket/key, "options":{"batchSize":10}}'                     |

其中，index和paths二选一。paths可以指定alias，否则内部随机生成alias返回用户。

可以使用 `options` JSON 来配置释放作业的选项。所有选项都是可选的。可能的配置有：

| **名称**         | **类型** | **必填** | **描述**                |
| -------------- | ------ | ------ | --------------------- |
| `batchSize`    | int    | 否      | worker每秒钟释放缓存文件的速度    |
| `replicas`     | int    | 否      | 释放文件副本的数量，仅在释放文件的时候有效 |
| `indexService` | bool   | 否      | 释放目录缓存                |

**示例**

一个 JSON 请求负载示例如下：

```json
{
    "paths": [
        "s3://tidas-alluxio-test/index",
        "s3://tidas-alluxio-test/index-copy"
    ],
    "options": {
        "batchSize": "30"
    }
}
```

正常返回示例：json格式

```
{
    "target": "job-0aafec67-53b4-488c-b988-73493b2b9ebe",
    "id": "bc0c3296-ea1f-484b-b371-300bf4d54ca6"
}
```

**错误码**

| **http状态码** | **错误码**               | **描述**                 |
| ----------- | --------------------- | ---------------------- |
| 200         | OK                    | 操作成功                   |
| 400         | Bad Request           | 请求没有正文或缺少必需字段          |
| 409         | Conflict              | 已经存在相同的job被调度，拒绝新任务的提交 |
| 500         | Internal Server Error | 意外错误                   |

#### 获取释放作业的进度

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/free | 有      | 无         |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                          |
| -------- | ------ | ------ | ------------ | ----------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | target=job-95e8a01f-d519-4c1a-8311-26714f4db623 |

注：3.7查询参数依然兼容， 例如:`alias`,`index`

**示例** 获取任务执行状态正常返回示例：json格式

````
```json
{
"id": "17bb4213-891b-4c3f-bc32-8d314051514b",
"startTime": "2026-01-17T21:59:11.831+08:00",
"endTime": "2026-01-17T21:59:16.104+08:00",
"jobState": "SUCCEEDED",
"timeElapsedMilliseconds": 4273,
"paths": [
    "s3://test/"
],
"alias": "job-95adb50b-4722-4a79-bd58-872cfeca48cb",
"freedBytes": 409600,
"totalBytes": 409600,
"freedFiles": 100,
"totalFiles": 100
````

} \`\`\`

**错误码**

| **http状态码** | **错误码**   | **描述** |
| ----------- | --------- | ------ |
| 200         | OK        | 操作成功   |
| 404         | Not Found | 任务不存在  |

#### 停止释放作业

| **方法** | **路径**       | **参数** | **请求体类型**                      |
| ------ | ------------ | ------ | ------------------------------ |
| DELETE | /api/v1/free | 无      | Content-Type: application/json |

**参数：**

| **名称**   | **类型** | **必填** | **描述**       | **示例**                                                |
| -------- | ------ | ------ | ------------ | ----------------------------------------------------- |
| `target` | string | 是      | 提交job时返回字段信息 | {"target":"job-95e8a01f-d519-4c1a-8311-26714f4db623"} |

注：3.7停止参数依然兼容， 例如:`alias`,`index`

**错误码**

| **http状态码** | **错误码**     | **描述**        |
| ----------- | ----------- | ------------- |
| 200         | OK          | 操作成功          |
| 400         | Bad Request | 请求没有正文或缺少必需字段 |
| 404         | Not Found   | 加载作业不存在       |
| 410         | Gone        | 加载作业已完成       |

#### 列出所有释放作业

| **方法** | **路径**       | **参数** | **请求体类型** |
| ------ | ------------ | ------ | --------- |
| GET    | /api/v1/free | 有      | 无         |

**参数：**

| **名称**    | **类型** | **必填** | **描述**                                 | **示例** |
| --------- | ------ | ------ | -------------------------------------- | ------ |
| `state`   | enum   | 否      | 作业状态\[RUNNING\|SUCCEEDED\|FAILED\|ALL] |        |
| `lastKey` | string | 否      | 从当前作键开始列举作业                            |        |
| `count`   | int    | 否      | 预期列出的作业数量                              |        |

注：没有参数将会列举所有job

**错误码**

| **http状态码** | **错误码** | **描述** |
| ----------- | ------- | ------ |
| 200         | OK      | 操作成功   |

**响应** 一个正常列举的响应：json格式

```
{
    "results": [
        {
            "id": "1498117f-bf66-4198-967d-1186588c56d1",
            "startTime": "2026-01-17T22:13:35.198+08:00",
            "endTime": "2026-01-17T22:13:40.385+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 5187,
            "paths": [
                "s3://test/rest1/test/"
            ],
            "alias": "job-312c44ac-156c-4e5a-b142-e540067ad086"
        },
        {
            "id": "3baf5ab6-c303-4a59-8678-f297870847f4",
            "startTime": "2026-01-17T22:13:26.177+08:00",
            "endTime": "2026-01-17T22:13:30.38+08:00",
            "jobState": "SUCCEEDED",
            "timeElapsedMilliseconds": 4203,
            "paths": [
                "s3://test/rest/test/"
            ],
            "alias": "job-749f2cbf-32cb-44d5-aa4f-4a4e6b94689b"
        }
    ]
}
```

### 重新平衡

#### 列出所有重新平衡作业

**方法：** `GET`

**路径：** `/api/v1/rebalance`

**参数：** 无

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {...}
    ]
  }
  ```

  有关作业描述的更多信息，请参阅 **“获取重新平衡作业的进度”**
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取重新平衡作业的进度

**方法：** `GET`

**路径：** `/api/v1/rebalance`

**参数：**

最多需要一个参数。

| **名称**   | **描述**                                                                                  |
| -------- | --------------------------------------------------------------------------------------- |
| `id`     | POST 返回的作业 ID                                                                           |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 worker-54b88939-de49-46ef-acab-fe489f46d1a0）或 ALL（表示所有工作节点） |

**响应：**

* `200 - OK`：操作成功（空值将被省略）

  ```json
  {
     "succeededWorkers":2,
     "bytesPreserved":4,
     "filesLoaded":0,
     "filesPreserved":1,
     "filesFailed":0,
     "totalWorkers":2,
     "bytesPruned":226,
     "filesPruned":5,
     "bytesLoaded":0,
     "timeElapsedMilliseconds":4536,
     "runningWorkers":0,
     "startTime":"2024-12-19T23:15:07.043+08:00",
     "id":"8de63d3a-63c8-4f08-bbc1-c87e3c0fb6d9",
     "state":"SUCCEEDED",
     "failedWorkers":0
  }
  ```
* `404 - Not Found`：未找到作业

  ```json
  {
    "status": "No job found..."
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 提交或恢复重新平衡作业

**方法：** `POST`

**路径：** `/api/v1/rebalance`

**参数：** 无

**请求体：** `Content-Type: application/json`

必需字段

| **名称**   | **描述**                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 `worker-54b88939-de49-46ef-acab-fe489f46d1a0`）或 `ALL`（表示所有工作节点） |

可以使用 `options` JSON 来配置加载作业的选项。所有选项都是可选的。可能的配置有：

| **名称**           | **描述**                              |
| ---------------- | ----------------------------------- |
| `loadBatchSize`  | 加载阶段的批处理大小，与加载作业中的 batchSize 选项相同   |
| `loadBandwidth`  | 每个工作节点每秒的加载带宽（字节）。例如：10485746000... |
| `pruneBandwidth` | 每个工作节点每秒的修剪带宽（字节）。例如：10485746000... |
| `skipPrune`      | 如果重新平衡应仅加载数据并跳过修剪不属于该工作节点的数据        |

一个 JSON 请求负载示例如下：

```json
{
  "target": "ALL",
  "options": {
    "loadBatchSize": 1000,
    "loadBandwidth": 10485746000,
    "pruneBandwidth": 10485746000,
    "skipPrune": false,
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：使用相同路径恢复加载作业并返回先前的作业 ID

  ```json
  {
    "id": "54b88939-de49-46ef-acab-fe489f46d1a0"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 停止重新平衡作业

**方法：** `DELETE`

**路径：** `/api/v1/rebalance`

**参数：** 无

**请求体：** `Content-Type: application/json`

最多需要一个参数。

| **名称**   | **描述**                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| `id`     | POST 返回的作业 ID                                                                               |
| `target` | 重新平衡作业的目标工作节点，可以是工作节点 ID（例如 `worker-54b88939-de49-46ef-acab-fe489f46d1a0`）或 `ALL`（表示所有工作节点） |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：作业不存在或已完成

  ```json
  {
    "status": "The job doesn't exist or has already finished"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 清理过时缓存

> 此操作与[释放缓存](#shi-fang-huan-cun)操作的不同之处在于：
>
> 1. 释放作业需要一个文件或目录列表作为输入参数，以指定要从工作节点中释放的内容。清理过时缓存操作不需要此类输入，因为“过时缓存”是通过扫描工作节点缓存存储并查询当前的一致性哈希环来自动确定的。
> 2. 释放作业需要设置正确的副本数，否则如果启用了文件复制，它可能会释放比预期少的副本。清理过时缓存操作只是向集群中的所有工作节点广播，因此它总是触发所有工作节点上的过时缓存清理，无论有多少副本。

#### 开始清理过时缓存

**方法：** `POST`

**路径：** `/api/v1/cache`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**响应：**

* `200 - OK`：一个空的错误对象表示操作已成功提交给所有工作节点执行

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`：非空的错误对象表示操作未能提交给至少一个工作节点执行

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：指定的操作类型未实现

  ```json
  {
    "status": "OP not implemented"
  }
  ```

#### 停止清理过时缓存

**方法：** `DELETE`

**路径：** `/api/v1/cache`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "op": "clear-stale"
}
```

**响应：**

* `200 - OK`：一个空的错误对象表示所有工作节点都已成功收到停止清理过时缓存的通知

  ```json
  {
    "errors": {}
  }
  ```
* `200 - OK`：非空的错误对象表示Coordinator未能通知至少一个工作节点停止清理过时缓存

  ```json
  {
    "errors": {
      "worker-host": "error message"
    }
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：指定的操作类型未实现

  ```json
  {
    "status": "OP not implemented"
  }
  ```

### 挂载表

#### 列出挂载点

**方法：** `GET`

**路径：** `/api/v1/mount`

**参数：** 无

**响应：**

* `200 - OK`：操作成功（如果为空，将省略选项）

  ```json
  {
    "results": [
      {
        "path": "/data/",
        "ufs": "s3://my-bucket/",
        "options": {
          "s3a.secretKey": "string",
          "s3a.accessKeyId": "string"
        }
      }
    ]
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取挂载点信息

**方法：** `GET`

**路径：** `/api/v1/mount`

**参数：**

| **名称** | **描述**          |
| ------ | --------------- |
| `path` | 挂载点的 alluxio 路径 |

**响应：**

* `200 - OK`：操作成功（如果为空，将省略选项）

  ```json
  {
    "path": "/data/",
    "ufs": "s3://my-bucket/",
    "options": {
      "s3a.secretKey": "string",
      "s3a.accessKeyId": "string"
    }
  }
  ```
* `404 - Not Found`：未找到挂载点

  ```json
  {
    "status": "No mount point found for path: /data/"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 创建挂载点

**方法：** `POST`

**路径：** `/api/v1/mount`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "path": "/data",
  "ufs": "s3://my-bucket",
  "options": {
    "s3a.secretKey": "string",
    "s3a.accessKeyId": "string"
  }
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `409 - Conflict`：该路径已挂载，或 UFS 已挂载到另一个路径

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：挂载表不支持通过 API 进行管理（例如：静态文件挂载表）

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除挂载点

**方法：** `DELETE`

**路径：** `/api/v1/mount`

**参数：** 无

**请求体：** `Content-Type: application/json`

```json
{
  "path": "/data"
}
```

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`：请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `410 - Gone`：该路径未挂载到任何 UFS

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`：挂载表不支持通过 API 进行管理（例如：静态文件挂载表）

  ```json
  {
    "status": "string"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 配额

#### 列出所有配额状态

**方法：** `GET`

**路径：** `/api/v1/quota`

**参数：** 无

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "state": "Available",
        "quotaBytes": 10737418240,
        "usedBytes": 9663676416,
        "reservedBytes": 1073741824
      }
    ]
  }
  ```
* `501 - Not Implemented`：未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`：意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取配额状态

**方法：** `GET`

**路径：** `/api/v1/quota`

**参数：**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应：**

* `200 - OK`：操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "state": "Available",
    "quotaBytes": 10737418240,
    "usedBytes": 9663676416,
    "reservedBytes": 1073741824
  }
  ```
* `404 - Not Found`: 未找到配额

  ```json
  {
    "status": "No quota item found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新配额

**方法:** `POST`

**路径:** `/api/v1/quota`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "quotaBytes": 10737418240
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必需字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 该路径未指向已挂载的 UFS，但必须与现有的 UFS绑定

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除配额

**方法:** `DELETE`

**路径:** `/api/v1/quota`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: ：请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 未找到配额或其他问题

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用配额

  ```json
  {
    "status": "Quota not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### TTL

#### 列出所有 TTL 策略

**方法:** `GET`

**路径:** `/api/v1/ttl`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
   {
    "results": [
      {
        "path": "/data/dir/to/path",
        "ttlSeconds": 600
      }
    ]
  }
  ```
* `501 - Not Implemented`: 未启用TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取 TTL 策略

**方法:** `GET`

**路径:** `/api/v1/ttl`

**参数:**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "ttlSeconds": 600
  }
  ```
* `404 - Not Found`: 未找到TTL

  ```json
  {
    "status": "No TTL policy found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新 TTL

**方法:** `POST`

**路径:** `/api/v1/ttl`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "ttlSeconds": 600
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 路径未指向已挂载的 UFS，但必须与现有的 UFS绑定

  ```json
  {
    "status": "No mounted UFS found"
  }
  ```
* `501 - Not Implemented`: 未启用 TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除 TTL

**方法:** `DELETE`

**路径:** `/api/v1/ttl`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 未找到TTL

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用 TTL 策略

  ```json
  {
    "status": "TTL not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 优先级驱逐

#### 列出所有优先级驱逐策略

**方法:** `GET`

**路径:** `/api/v1/priority`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "results": [
      {
        "path": "/data/dir/to/path",
        "priority": "high"
      }
    ]
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 获取优先级驱逐策略

**方法:** `GET`

**路径:** `/api/v1/priority`

**参数:**

| **名称** | **描述**         |
| ------ | -------------- |
| `path` | 数据的 alluxio 路径 |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "path": "/data/dir/to/path",
    "priority": "high"
  }
  ```
* `404 - Not Found`: 未找到优先级驱逐策略

  ```json
  {
    "status": "No priority rule found for path: /data/dir/to/path"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 添加或更新优先级

**方法:** `POST`

**路径:** `/api/v1/priority`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path",
  "priority": "high"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `400 - Bad Request`: 优先级字符串格式错误或存在其他问题

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 删除优先级策略

**方法:** `DELETE`

**路径:** `/api/v1/priority`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "path": "/data/dir/to/path"
}
```

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `501 - Not Implemented`: 未启用优先级驱逐

  ```json
  {
    "status": "Priority eviction not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 节点管理

#### 列出所有节点

**方法:** `GET`

**路径:** `/api/v1/nodes`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "result": [
      {
        "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
        "address": "192.168.1.19:29989",
        "status": "ONLINE"
      },
      {
        "identity": "worker-844db66c-d7fd-46cc-8de0-2f3989360828",
        "address": "192.168.1.19:29999",
        "status": "OFFLINE"
      }
    ]
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 查询节点

**方法:** `GET`

**路径:** `/api/v1/nodes`

**参数:**

| **名称** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| `id`   | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**响应:**

* `200 - OK`: 操作成功\
  (空值将被省略)

  ```json
  {
    "identity": "worker-587899dd-5da5-45d4-af40-ce481acc4087",
    "address": "192.168.1.19:29989",
    "status": "ONLINE"
  }
  ```
* `404 - Not Found`: 未找到worker

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 注销节点（从 etcd 中移除节点）

**方法:** `DELETE`

**路径:** `/api/v1/nodes`

**参数:**

| **名称** | **描述**                                                       |
| ------ | ------------------------------------------------------------ |
| `id`   | worker id (e.g. worker-587899dd-5da5-45d4-af40-ce481acc4087) |

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "status": "ok"
  }
  ```
* `404 - Not Found`: 未找到worker

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 全局文件索引

#### 列出所有节点

**方法:** `GET`

**路径:** `/api/v1/file_index`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

  ```json
  {
    "results": [
      "file:///home/yimin/alluxio/ufs/10MB",
      "file:///home/yimin/alluxio/ufs/to_load/f1"
    ]
  }
  ```
* `500 - Internal Server Error`:意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 将文件添加到全局文件索引

**方法:** `POST`

**路径:** `/api/v1/file_index`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**响应:**

* `200 - OK`: 操作成功（已添加条目数）

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: 功能未启用

  ```json
  {
    "status": "Global file index is not enabled"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

#### 从全局文件索引中移除文件

**方法:** `DELETE`

**路径:** `/api/v1/file_index`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "files": [
    "s3://foo/bar/f1",
    "s3://foo/bar/f2"
  ]
}
```

**响应:**

* `200 - OK`: 操作成功（已移除条目数）

  ```json
  {
    "entries": 10
  }
  ```
* `404 - Not Found`: 功能未启用

  ```json
  {
    "status": "worker not found..."
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```

### 缓存过滤

#### 列出所有缓存过滤规则

**方法:** `GET`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**响应:**

* `200 - OK`: 操作成功

```json
{
  "results": [
    {
      "apiVersion": 1,
      "type": "metadata",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": ["s3://bucket/mutable-dir/.*"],
        "immutable": ["s3://bucket/immutable-dir/.*"],
        "maxAge": {"s3://bucket/auto-refresh/.*":  "1d"}
      }
    },
    {
      "apiVersion": 1,
      "type": "data",
      "rules": {
        "defaultType": "immutable",
        "defaultMaxAge": null,
        "skipCache": [],
        "immutable": [],
        "maxAge": {}
      }
    }
  ]
}
```

* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### 添加缓存过滤规则或更新默认规则

**方法:** `POST`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

如果规则是 `maxAge`, 则需要指定 `time` 。

```json
{
  "type": "data",
  "rule": "maxAge",
  "pattern": "s3a://auto-refresh/c/.*",
  "time": "1d"
}
```

如果要更新默认规则，请设置 `updateDefault`。无需指定 `pattern` ，因为所有未匹配其他规则的路径都将由默认规则捕获。

```json
{
  "type": "metadata",
  "rule": "skipCache",
  "updateDefault": true
}
```

**响应:**

* `200 - OK`: 操作成功
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```

#### 移除缓存过滤规则

**方法:** `DELETE`

**路径:** `/api/v1/cache-filter`

**参数:** 无

**请求体:** `Content-Type: application/json`

```json
{
  "type": "data",
  "rule": "skipCache",
  "pattern": "s3a://data-bucket/c/.*"
}
```

如果规则是`maxAge`.，无需指定`time`。此外，默认规则无法删除，只能将默认规则更改为其他规则。

**响应:**

* `200 - OK`: 操作成功
* `400 - Bad Request`: 请求没有正文或缺少必填字段

  ```json
  {
    "status": "Required parameters not provided"
  }
  ```
* `500 - Internal Server Error`: 意外错误

  ```json
  {
    "status": "string"
  }
  ```
* `501 - Not Implemented`: 未启用缓存过滤

  ```json
  {
    "status": "Cache filter not enabled"
  }
  ```