メディア API

画像・動画のメディアを管理するエンドポイントです。 ユーザーがアップロードしたファイルのほか、thumbnail_generation Lambda が生成したサムネイル画像も このコレクションで管理します。

メディアスキーマ

フィールド	データ型	備考
id	string	_id
name	string	ユニーク。S3 のオブジェクトキーにもなる
mime_type	enum	image / video
s3_url	string	参照用 URL。取得系レスポンスでは有効期限 1 時間の署名付き URL を都度生成して返す
size	number	バイト数
race_id	string | null	紐づくレースの _id。サムネイルなどレース由来のメディアのみ設定され、汎用アップロードでは null
created_at	number	UNIXタイムスタンプ（ミリ秒）
updated_at	number	UNIXタイムスタンプ（ミリ秒）

race_id は API から設定できない

race_id は thumbnail_generation Lambda がサムネイルを保存するときにのみ設定します。 メディア API の作成・更新では指定できません。

---

POST /v1/medias

概要

メディアを新規登録します。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

• Content-Type: multipart/form-data

レスポンスヘッダー

• Content-Type: application/json

URI

POST /v1/medias

リクエストボディ

multipart/form-data 形式でファイルとメタデータを送信します。

フィールド	データ型	必須	備考
name	string	◯	ユニーク
mime_type	enum	◯	image / video
file	binary	◯	アップロードするファイル

レスポンス

201 Created

{
  "id": "string",
  "name": "string",
  "mime_type": "image",
  "s3_url": "string",
  "size": 1024,
  "race_id": null,
  "created_at": 1234567890000,
  "updated_at": 1234567890000
}

例外処理

説明	ステータスコード	ステータス名
リクエストボディが不正	422	Unprocessable Entity
nameが既に存在する	409	Conflict
S3アップロード失敗	500	Internal Server Error
内部サーバーエラー	500	Internal Server Error

処理フロー

1. リクエストを受信する
2. リクエストをバリデーションする
3. name の重複チェックを行う
4. ファイルをS3にアップロードする
5. S3から返却されたURLとファイルサイズをDBに保存する
6. 作成したメディアを返す

flowchart TD
    Start([POST /v1/medias]) --> Validate[リクエストバリデーション]
    Validate -->|invalid| E422[422 Unprocessable Entity]
    Validate -->|valid| NameCheck[name 重複チェック]
    NameCheck -->|重複あり| E409[409 Conflict]
    NameCheck -->|重複なし| S3Upload[S3にアップロード]
    S3Upload -->|失敗| E500[500 Internal Server Error]
    S3Upload -->|成功 URL・サイズ取得| Save[DBに保存]
    Save --> Success[201 Created]

---

GET /v1/medias

概要

メディアの一覧を取得します。

リクエストとレスポンス

URI

GET /v1/medias

クエリパラメータ

パラメータ	データ型	必須	備考
mime_type	enum		image / video でフィルタ
page	number		取得するページ番号。デフォルト: 1
size	number		1ページあたりの件数。デフォルト: 10
order	enum		asc / desc（updated_at 基準）。デフォルト: desc

リクエストボディ

なし

レスポンス

200 OK

{
  "list": [
    {
      "id": "string",
      "name": "string",
      "mime_type": "image",
      "s3_url": "string",
      "size": 1024,
      "race_id": null,
      "created_at": 1234567890000,
      "updated_at": 1234567890000
    }
  ],
  "current_page": 1,
  "total_count": 10
}

例外処理

説明	ステータスコード	ステータス名
内部サーバーエラー	500	Internal Server Error

処理フロー

1. リクエストを受信する
2. クエリパラメータでフィルタしてメディア一覧を取得する
3. 一覧を返す

flowchart TD
    Start([GET /v1/medias]) --> Fetch[DBからメディア一覧取得]
    Fetch --> Success[200 OK]

---

GET /v1/medias/{media_id}

概要

指定したメディアを取得します。

リクエストとレスポンス

URI

GET /v1/medias/{media_id}

パスパラメータ	データ型	備考
media_id	string	_id

リクエストボディ

なし

レスポンス

200 OK

{
  "id": "string",
  "name": "string",
  "mime_type": "image",
  "s3_url": "string",
  "size": 1024,
  "race_id": null,
  "created_at": 1234567890000,
  "updated_at": 1234567890000
}

例外処理

説明	ステータスコード	ステータス名
メディアが存在しない	404	Not Found
内部サーバーエラー	500	Internal Server Error

処理フロー

1. リクエストを受信する
2. media_id でメディアを検索する
3. メディアを返す

flowchart TD
    Start([GET /v1/medias/media_id]) --> Fetch[DBから検索]
    Fetch -->|存在しない| E404[404 Not Found]
    Fetch -->|存在する| Success[200 OK]

---

PUT /v1/medias/{media_id}

概要

指定したメディアを更新します。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

• Content-Type: multipart/form-data

レスポンスヘッダー

• Content-Type: application/json

URI

PUT /v1/medias/{media_id}

パスパラメータ	データ型	備考
media_id	string	_id

リクエストボディ

multipart/form-data 形式で送信します。ファイルを省略した場合はメタデータのみ更新します。

フィールド	データ型	必須	備考
name	string		ユニーク
mime_type	enum		image / video
file	binary		差し替えるファイル。指定した場合はS3を上書きアップロード

レスポンス

200 OK

{
  "id": "string",
  "name": "string",
  "mime_type": "image",
  "s3_url": "string",
  "size": 1024,
  "race_id": null,
  "created_at": 1234567890000,
  "updated_at": 1234567890000
}

例外処理

説明	ステータスコード	ステータス名
リクエストボディが不正	422	Unprocessable Entity
メディアが存在しない	404	Not Found
nameが既に存在する	409	Conflict
S3アップロード失敗	500	Internal Server Error
内部サーバーエラー	500	Internal Server Error

処理フロー

1. リクエストを受信する
2. リクエストをバリデーションする
3. メディアの存在確認をする
4. name を変更する場合は重複チェックを行う
5. file が指定されている場合はS3に上書きアップロードし、URLとサイズを更新する
6. メディアを更新して保存する
7. 更新したメディアを返す

flowchart TD
    Start([PUT /v1/medias/media_id]) --> Validate[リクエストバリデーション]
    Validate -->|invalid| E422[422 Unprocessable Entity]
    Validate -->|valid| Fetch[DBから検索]
    Fetch -->|存在しない| E404[404 Not Found]
    Fetch -->|存在する| NameCheck[name 重複チェック]
    NameCheck -->|重複あり| E409[409 Conflict]
    NameCheck -->|重複なし| FileCheck{file 指定あり?}
    FileCheck -->|あり| S3Upload[S3に上書きアップロード]
    S3Upload -->|失敗| E500[500 Internal Server Error]
    S3Upload -->|成功 URL・サイズ更新| Save[DBに保存]
    FileCheck -->|なし| Save
    Save --> Success[200 OK]

---

DELETE /v1/medias/{media_id}

概要

指定したメディアを論理削除します。

リクエストとレスポンス

URI

DELETE /v1/medias/{media_id}

パスパラメータ	データ型	備考
media_id	string	_id

リクエストボディ

なし

レスポンス

204 No Content

例外処理

説明	ステータスコード	ステータス名
メディアが存在しない	404	Not Found
内部サーバーエラー	500	Internal Server Error

処理フロー

1. リクエストを受信する
2. メディアの存在確認をする
3. deleted_at に現在時刻を設定して保存する（論理削除）
4. 204 を返す

flowchart TD
    Start([DELETE /v1/medias/media_id]) --> Fetch[DBから検索]
    Fetch -->|存在しない| E404[404 Not Found]
    Fetch -->|存在する| Delete[deleted_at を設定]
    Delete --> Success[204 No Content]