# Mini-VPS Object Storage API Documentation

Mini-VPS のオブジェクトストレージを操作するためのREST API仕様書です。

このAPIを使用することで、アプリケーションから直接ファイルのアップロード、一覧取得、削除、アクセス制御を行うことができます。

### 🌐 基本情報 (General Info)

* Base URL: `https://mini-vps.mixeder.com/api/storage`
* 課金について:
  * ストレージ操作（アップロード、削除、一覧取得）は、ユーザーのクレジット残高を使用します。
  * クレジットが `0` 以下の場合、アップロードやAPI操作は `402 Payment Required` エラーとなります。

### 🔑 認証 (Authentication)

APIを利用するには、以下のいずれかの認証が必要です。

#### 1. APIキー認証 (推奨: 外部アプリ向け)

バケットごとに発行されたAPIキーを使用します。特定のバケットに対する操作のみが許可されます。

* Header Name: `x-api-key`
* Value: バケット設定画面で発行したAPIキー

#### 2. セッション認証 (ブラウザ・管理画面向け)

ブラウザでログイン済みの場合、セッションを利用して認証します。バケットの作成や削除など、管理者権限が必要な操作に使用します。

***

### 📂 1. ファイル操作 (File Operations)

#### 1.1 ファイル一覧取得 (List Files)

指定したバケット内のファイルとフォルダ構造を取得します。

* Endpoint: `GET /files/list`
* Auth: API Key / Session
* Use Case: ファイルマネージャーの表示、画像ギャラリーの構築。

**パラメータ (Query Parameters)**

| **パラメータ**  | **必須** | **説明**                       | **例**          |
| ---------- | ------ | ---------------------------- | -------------- |
| `bucketId` | ✅      | 対象のバケットID                    | `b1234-uuid`   |
| `prefix`   |        | 特定フォルダ内を表示する場合のパス (末尾に`/`必須) | `images/2024/` |

**cURL Request**

Bash

```bash
curl -G "https://mini-vps.mixeder.com/api/storage/files/list" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  --data-urlencode "bucketId=YOUR_BUCKET_ID" \
  --data-urlencode "prefix=photos/"
```

**Response Example**

JSON

```json
{
  "success": true,
  "currentPrefix": "photos/",
  "folders": [
    { "name": "2024", "path": "photos/2024/", "type": "folder" }
  ],
  "files": [
    { 
      "name": "vacation.jpg", 
      "path": "photos/vacation.jpg", 
      "size": 1048576, 
      "lastModified": "2024-02-07T12:00:00.000Z", 
      "type": "file" 
    }
  ]
}
```

***

#### 1.2 ファイルアップロード (Upload File)

ファイルをバケットにアップロードします。成功時、課金用ストレージ容量が加算されます。

* Endpoint: `POST /file/upload`
* Auth: API Key / Session
* Content-Type: `multipart/form-data`
* Use Case: ユーザーアイコンのアップロード、バックアップデータの保存。

**パラメータ (Form Data)**

| **パラメータ**      | **必須** | **説明**                                 |
| -------------- | ------ | -------------------------------------- |
| `file`         | ✅      | バイナリデータ (File Object)                  |
| `bucketId`     | ✅      | アップロード先のバケットID                         |
| `targetPrefix` |        | 保存先フォルダパス (例: `uploads/`)。指定しない場合はルート。 |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/file/upload" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -F "bucketId=YOUR_BUCKET_ID" \
  -F "targetPrefix=uploads/images/" \
  -F "file=@/local/path/to/image.png"
```

**Response Example**

JSON

```
{
  "success": true,
  "size": 10245000 // 更新後のバケット合計サイズ(bytes)
}
```

***

#### 1.3 ファイル削除 (Delete File)

ファイルを削除し、ストレージ容量を解放します。

* Endpoint: `POST /file/delete`
* Auth: API Key / Session
* Content-Type: `application/json`

**パラメータ (JSON Body)**

| **パラメータ**  | **必須** | **説明**                                      |
| ---------- | ------ | ------------------------------------------- |
| `bucketId` | ✅      | バケットID                                      |
| `key`      | ✅      | 削除するファイルのパス (例: `uploads/images/image.png`) |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/file/delete" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "key": "uploads/images/image.png"
  }'
```

***

### 📁 2. フォルダ操作 (Folder Operations)

#### 2.1 フォルダ作成 (Create Folder)

空のフォルダ（プレフィックス）を作成します。

※ オブジェクトストレージの仕様上、0バイトのオブジェクトとして作成されます。

* Endpoint: `POST /folder/create`
* Auth: API Key / Session

**パラメータ (JSON Body)**

| **パラメータ**       | **必須** | **説明**                       |
| --------------- | ------ | ---------------------------- |
| `bucketId`      | ✅      | バケットID                       |
| `folderName`    | ✅      | 作成するフォルダ名 (例: `new_docs`)    |
| `currentPrefix` |        | 親フォルダがある場合 (例: `project_a/`) |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/folder/create" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "folderName": "logs",
    "currentPrefix": "server_a/"
  }'
# 結果: "server_a/logs/" が作成されます
```

***

#### 2.2 フォルダ一括削除 (Delete Folder)

指定したフォルダと、その中にあるすべてのファイルを再帰的に削除します。

※ 削除されたファイル分の容量がクレジット計算から減算されます。取り消しできません。

* Endpoint: `POST /folder/delete`
* Auth: API Key / Session

**パラメータ (JSON Body)**

| **パラメータ**    | **必須** | **説明**                            |
| ------------ | ------ | --------------------------------- |
| `bucketId`   | ✅      | バケットID                            |
| `folderPath` | ✅      | 削除対象のフォルダパス (例: `server_a/logs/`) |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/folder/delete" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "folderPath": "server_a/logs/"
  }'
```

***

### 🔗 3. アクセス共有 (Access Control)

#### 3.1 署名付きURL発行 (Generate Signed URL)

プライベートなファイルに対して、一定時間だけアクセス可能なURLを発行します。

* Endpoint: `POST /url/sign`
* Auth: API Key / Session
* Use Case: チャットでのファイル共有、期限付きダウンロードリンク。

**パラメータ (JSON Body)**

| **パラメータ**  | **必須** | **説明**    |
| ---------- | ------ | --------- |
| `bucketId` | ✅      | バケットID    |
| `key`      | ✅      | 対象ファイルのパス |

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/url/sign" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "YOUR_BUCKET_ID",
    "key": "private/contract.pdf"
  }'
```

**Response Example**

JSON

```
{
  "success": true,
  "url": "/s/my-bucket/private/contract.pdf?expires=1738999999&signature=a1b2c3d4..."
}
```

※ ブラウザでこのURLにアクセスするとファイルが表示・ダウンロードされます。

***

### ⚙️ 4. 管理・設定 (Management)

これらのAPIは通常、APIキーではなく\*\*セッション認証（管理画面）\*\*から呼び出されます。

#### 4.1 バケット作成 (Create Bucket)

* Endpoint: `POST /create`
* Auth: Session Only (Cookie)
* Body: `{ "bucketName": "unique-name" }`

#### 4.2 バケット削除 (Delete Bucket)

バケットごと全データを削除します。

* Endpoint: `POST /delete`
* Auth: Session Only (Cookie)
* Body: `{ "bucketId": "..." }`

#### 4.3 容量同期 (Sync Stats)

データベース上の容量表示と、実際のクラウドストレージ上の容量にズレが生じた場合に実行し、正しい値に修正します。

* Endpoint: `POST /sync`
* Auth: API Key / Session
* Body: `{ "bucketId": "..." }`

**cURL Request**

Bash

```
curl -X POST "https://mini-vps.mixeder.com/api/storage/sync" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "bucketId": "YOUR_BUCKET_ID" }'
```

***

#### 4.4 APIキー管理

* 作成: `POST /apikey/create` - Body: `{ "bucketId": "..." }`
* 削除: `POST /apikey/delete` - Body: `{ "bucketId": "...", "apiKey": "..." }`

***

### 🚨 エラーコード一覧 (Error Codes)

APIはHTTPステータスコードで成否を返します。レスポンスボディには `{ "error": "詳細メッセージ" }` が含まれます。

| **Status** | **Code** | **説明**           | **対処法**                       |
| ---------- | -------- | ---------------- | ----------------------------- |
| ✅          | 200      | OK               | リクエスト成功。                      |
| ❌          | 400      | Bad Request      | パラメータ不足、またはファイルサイズ制限超過。       |
| ❌          | 401      | Unauthorized     | ログインしていない、またはセッション切れ。         |
| ❌          | 402      | Payment Required | クレジット残高不足。チャージしてください。         |
| ❌          | 403      | Forbidden        | APIキーが無効、または対象バケットへの権限がありません。 |
| ❌          | 404      | Not Found        | 指定されたバケットIDやファイルが存在しません。      |
| ❌          | 500      | Server Error     | サーバー内部エラー。管理者へ連絡してください。       |