convertor/docs/05-API文件.md

# API 文件

ConvertX-CN 提供選用的 API Server，支援 REST 和 GraphQL 兩種 API 介面。

---

## 目錄

- [快速啟用](#快速啟用)
- [認證機制](#認證機制)
- [REST API 端點](#rest-api-端點)
- [GraphQL API](#graphql-api)
- [錯誤碼說明](#錯誤碼說明)
- [使用範例](#使用範例)

---

## 快速啟用

API Server 是**選用功能**，不影響 Web UI 使用。

### 啟用方式

```bash
docker compose --profile api up -d
```

### 服務端口

| 服務       | 端口 | 說明           |
| ---------- | ---- | -------------- |
| Web UI     | 3000 | 網頁介面       |
| API Server | 3001 | REST & GraphQL |

### 環境變數

| 變數            | 說明                  | 預設值           |
| --------------- | --------------------- | ---------------- |
| `API_HOST`      | 監聽地址              | `0.0.0.0`        |
| `API_PORT`      | 監聽埠                | `3001`           |
| `JWT_SECRET`    | JWT 驗證密鑰          | （需自行設定）   |
| `UPLOAD_DIR`    | 上傳目錄              | `./data/uploads` |
| `OUTPUT_DIR`    | 輸出目錄              | `./data/output`  |
| `MAX_FILE_SIZE` | 最大檔案大小（bytes） | `104857600`      |

---

## 認證機制

所有 API 請求（除健康檢查外）都需要 JWT Bearer Token：

```http
Authorization: Bearer <your-jwt-token>
```

### Token 結構

```json
{
  "sub": "user-id",
  "exp": 1234567890,
  "iat": 1234567890,
  "email": "user@example.com",
  "roles": ["user"]
}
```

> ⚠️ **注意**：API Server 只負責驗證 JWT，不負責產生 JWT。Token 應由獨立的認證服務產生。

---

## REST API 端點

**Base URL**: `http://localhost:3001/api/v1`

### 健康檢查

檢查 API Server 運行狀態。

**請求**：

```http
GET /health
```

**回應**：

```json
{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-01-25T10:30:00Z"
}
```

---

### 取得支援格式

取得所有支援的輸入/輸出格式。

**請求**：

```http
GET /api/v1/formats
Authorization: Bearer <token>
```

**回應**：

```json
{
  "converters": [
    {
      "name": "ffmpeg",
      "inputFormats": ["mp4", "mkv", "avi", "..."],
      "outputFormats": ["mp4", "webm", "mp3", "..."]
    },
    {
      "name": "imagemagick",
      "inputFormats": ["png", "jpg", "heic", "..."],
      "outputFormats": ["png", "jpg", "webp", "..."]
    }
  ]
}
```

---

### 上傳檔案

上傳待轉換的檔案。

**請求**：

```http
POST /api/v1/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary>
```

**回應**：

```json
{
  "success": true,
  "fileId": "abc123",
  "filename": "document.docx",
  "size": 1048576,
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}
```

---

### 開始轉換

對已上傳的檔案進行轉換。

**請求**：

```http
POST /api/v1/convert
Authorization: Bearer <token>
Content-Type: application/json

{
  "fileId": "abc123",
  "outputFormat": "pdf",
  "options": {
    "quality": "high"
  }
}
```

**回應**：

```json
{
  "success": true,
  "jobId": "job456",
  "status": "processing",
  "estimatedTime": 30
}
```

---

### 查詢轉換狀態

取得轉換任務的當前狀態。

**請求**：

```http
GET /api/v1/jobs/{jobId}
Authorization: Bearer <token>
```

**回應（處理中）**：

```json
{
  "jobId": "job456",
  "status": "processing",
  "progress": 45,
  "message": "Converting page 3 of 10..."
}
```

**回應（完成）**：

```json
{
  "jobId": "job456",
  "status": "completed",
  "progress": 100,
  "result": {
    "fileId": "result789",
    "filename": "document.pdf",
    "size": 524288,
    "downloadUrl": "/api/v1/download/result789"
  }
}
```

---

### 下載結果

下載轉換完成的檔案。

**請求**：

```http
GET /api/v1/download/{fileId}
Authorization: Bearer <token>
```

**回應**：

```
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

<binary content>
```

---

### 刪除檔案

刪除已上傳或轉換完成的檔案。

**請求**：

```http
DELETE /api/v1/files/{fileId}
Authorization: Bearer <token>
```

**回應**：

```json
{
  "success": true,
  "message": "File deleted successfully"
}
```

---

## GraphQL API

**Endpoint**: `http://localhost:3001/graphql`

### Schema 概覽

```graphql
type Query {
  health: Health!
  formats: [Converter!]!
  job(id: ID!): Job
  jobs: [Job!]!
}

type Mutation {
  upload(file: Upload!): UploadResult!
  convert(input: ConvertInput!): ConvertResult!
  deleteFile(fileId: ID!): DeleteResult!
}

type Health {
  status: String!
  version: String!
  timestamp: String!
}

type Converter {
  name: String!
  inputFormats: [String!]!
  outputFormats: [String!]!
}

type Job {
  id: ID!
  status: JobStatus!
  progress: Int!
  message: String
  result: ConvertedFile
}

enum JobStatus {
  PENDING
  PROCESSING
  COMPLETED
  FAILED
}
```

### 查詢範例

**取得所有格式**：

```graphql
query {
  formats {
    name
    inputFormats
    outputFormats
  }
}
```

**查詢任務狀態**：

```graphql
query {
  job(id: "job456") {
    status
    progress
    message
    result {
      filename
      size
      downloadUrl
    }
  }
}
```

### 變更範例

**開始轉換**：

```graphql
mutation {
  convert(input: { fileId: "abc123", outputFormat: "pdf", options: { quality: "high" } }) {
    jobId
    status
  }
}
```

---

## 錯誤碼說明

### HTTP 狀態碼

| 狀態碼 | 說明       | 常見原因             |
| ------ | ---------- | -------------------- |
| 200    | 成功       | 請求正常處理         |
| 400    | 錯誤請求   | 參數錯誤、格式不支援 |
| 401    | 未授權     | Token 無效或過期     |
| 403    | 禁止存取   | 權限不足             |
| 404    | 找不到     | 檔案或任務不存在     |
| 413    | 檔案太大   | 超過上傳限制         |
| 415    | 格式不支援 | 不支援的檔案類型     |
| 500    | 伺服器錯誤 | 內部錯誤             |
| 503    | 服務不可用 | 伺服器過載           |

### 錯誤回應格式

```json
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FORMAT",
    "message": "The format 'xyz' is not supported",
    "details": {
      "inputFormat": "xyz",
      "supportedFormats": ["pdf", "docx", "png"]
    }
  }
}
```

### 常見錯誤碼

| 錯誤碼               | 說明       | 解決方法           |
| -------------------- | ---------- | ------------------ |
| `INVALID_TOKEN`      | Token 無效 | 重新取得有效 Token |
| `TOKEN_EXPIRED`      | Token 過期 | 刷新 Token         |
| `FILE_NOT_FOUND`     | 檔案不存在 | 確認檔案 ID 正確   |
| `UNSUPPORTED_FORMAT` | 格式不支援 | 查看支援格式列表   |
| `FILE_TOO_LARGE`     | 檔案過大   | 壓縮或分割檔案     |
| `CONVERSION_FAILED`  | 轉換失敗   | 檢查檔案是否損壞   |
| `RATE_LIMITED`       | 請求過頻繁 | 降低請求頻率       |

---

## 使用範例

### cURL 範例

**上傳並轉換檔案**：

```bash
# 1. 上傳檔案
FILE_RESPONSE=$(curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@document.docx" \
  http://localhost:3001/api/v1/upload)

FILE_ID=$(echo $FILE_RESPONSE | jq -r '.fileId')

# 2. 開始轉換
JOB_RESPONSE=$(curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"fileId\": \"$FILE_ID\", \"outputFormat\": \"pdf\"}" \
  http://localhost:3001/api/v1/convert)

JOB_ID=$(echo $JOB_RESPONSE | jq -r '.jobId')

# 3. 等待完成並下載
sleep 10

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3001/api/v1/download/$FILE_ID \
  -o output.pdf
```

### Python 範例

```python
import requests

BASE_URL = "http://localhost:3001/api/v1"
TOKEN = "your-jwt-token"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 上傳檔案
with open("document.docx", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/upload",
        headers=HEADERS,
        files={"file": f}
    )
    file_id = response.json()["fileId"]

# 開始轉換
response = requests.post(
    f"{BASE_URL}/convert",
    headers=HEADERS,
    json={"fileId": file_id, "outputFormat": "pdf"}
)
job_id = response.json()["jobId"]

# 輪詢狀態
import time
while True:
    response = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS)
    status = response.json()["status"]
    if status == "completed":
        break
    time.sleep(2)

# 下載結果
result_id = response.json()["result"]["fileId"]
response = requests.get(f"{BASE_URL}/download/{result_id}", headers=HEADERS)
with open("output.pdf", "wb") as f:
    f.write(response.content)
```

### JavaScript 範例

```javascript
const BASE_URL = "http://localhost:3001/api/v1";
const TOKEN = "your-jwt-token";

async function convertFile(file, outputFormat) {
  // 上傳檔案
  const formData = new FormData();
  formData.append("file", file);

  const uploadResponse = await fetch(`${BASE_URL}/upload`, {
    method: "POST",
    headers: { Authorization: `Bearer ${TOKEN}` },
    body: formData,
  });
  const { fileId } = await uploadResponse.json();

  // 開始轉換
  const convertResponse = await fetch(`${BASE_URL}/convert`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ fileId, outputFormat }),
  });
  const { jobId } = await convertResponse.json();

  // 輪詢狀態
  let result;
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${TOKEN}` },
    });
    const job = await statusResponse.json();
    if (job.status === "completed") {
      result = job.result;
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  // 下載結果
  const downloadResponse = await fetch(`${BASE_URL}/download/${result.fileId}`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  return await downloadResponse.blob();
}
```

---

[⬆️ 回到頂部](#api-文件) | [📚 回到目錄](00-專案總覽.md)