Mini-VPS Object Storage API Documentation

Learn more about documenting APIs in GitBook.

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

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

{
  "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	サーバー内部エラー。管理者へ連絡してください。