コンテンツにスキップ

ワイヤーフレーム作成

メソッド

RESTメソッドを採用しています。

HTTPメソッド

POST: ワイヤーフレーム作成（Figma URLからインポート）

命名規則

クエリパラメータとノードの命名を統一し、可読性を向上させるため、リクエスト時のURIとJSON内のノードにはsnake_caseを使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTPヘッダーに設定されます。

リクエストヘッダー

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

ワイヤーフレーム作成

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wireframes

パスパラメータ

名前 型 必須 説明
organization_id integer 必須 組織ID
project_id integer 必須 プロジェクトID

リクエストボディ

リクエストボディはJSONです。

{
  "figma_url": "https://www.figma.com/file/ABC123/Design-File?node-id=2585:942"
}

リクエストパラメータ

名前 型 必須 説明
figma_url string 必須 Figma URL（file または design）

レスポンス

レスポンスはJSONです（HTTPステータス: 201 Created）。

{
  "id": "ABC123_2585:942",
  "projectId": 1,
  "s3Key": null,
  "frameName": null,
  "status": 0,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-id",
  "updatedBy": "user-id",
  "deletedBy": null
}

ステータス値

値 説明
0 保留中
1 処理中
2 完了
3 失敗

レスポンスフィールド

名前 型 説明
id string ワイヤーフレームID（形式: fileId_nodeId）
projectId number プロジェクトID
s3Key string | null S3オブジェクトキー（処理完了後に設定）
frameName string | null Figmaフレーム名（処理完了後に設定）
status number 処理ステータス（0-3）
createdAt number 作成日時（エポックミリ秒）
updatedAt number 更新日時（エポックミリ秒）
deletedAt number | null 削除日時（エポックミリ秒）。未削除の場合はnull
createdBy string 作成者のユーザーID
updatedBy string 更新者のユーザーID
deletedBy string | null 削除者のユーザーID。未削除の場合はnull

認証

認証はAmazon Cognitoから発行されるJSON Web Tokens (JWT)を使用して行われます。

例外処理

例外処理のステータスコードは以下の通りです。

説明 ステータスコード ステータス名
無効なFigma URLフォーマット 400 Bad Request
認証情報不足 401 Unauthorized
実行権限不足 403 Forbidden
プロジェクトまたは組織が見つかりません 404 Not Found
内部サーバーエラー 500 Internal Server Error

処理フロー

  1. Figma URLをパースしてfileIdとnodeIdを抽出
  2. ユーザーのFigma PATを取得
  3. Figma APIからワイヤーフレームデータと画像を取得（並行処理）
  4. 画像とJSONスキーマをS3にアップロード（並行処理）
  5. SQSに処理メッセージを送信
  6. データベースにワイヤーフレームレコードを作成
  7. 初期ステータス0（保留中）でレスポンスを返す

詳細フローチャート

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[認証・パラメータ取得]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[権限チェック]
    AccessCheck --> HasAccess{Write権限?}
    HasAccess -->|なし| Err404[404 Not Found]
    HasAccess -->|あり| ParseURL[Figma URL解析]

    ParseURL --> ValidURL{有効なURL?}
    ValidURL -->|NG| Err400[400 Bad Request]
    ValidURL -->|OK| GetToken[Figma PAT取得]

    GetToken --> HasToken{トークン存在?}
    HasToken -->|なし| Err400
    HasToken -->|あり| ParallelFetch[並列Figma API呼び出し]

    ParallelFetch --> FetchImage[Figma画像取得]
    ParallelFetch --> FetchSchema[ワイヤーフレームデータ取得]

    FetchImage --> ParallelS3[並列S3アップロード]
    FetchSchema --> ParallelS3

    ParallelS3 --> UploadImage[画像アップロード]
    ParallelS3 --> UploadJSON[JSONアップロード]

    UploadImage --> CheckUploads{アップロード成功?}
    UploadJSON --> CheckUploads

    CheckUploads -->|NG| Err500[500 Internal Error]
    CheckUploads -->|OK| SQSSend[SQSメッセージ送信]

    SQSSend --> SQSOK{成功?}
    SQSOK -->|NG| Err500
    SQSOK -->|OK| CreateDB[DBレコード作成<br/>status=0 pending]

    CreateDB --> Success[201 Created<br/>非同期処理開始]

非同期処理

ワイヤーフレームは非同期で処理されます。バックグラウンドワーカーがステータスを更新します： - 0 (保留中) → 1 (処理中) → 2 (完了) または 3 (失敗)

Figma URL フォーマット

有効なFigma URL形式： - https://www.figma.com/file/{fileId}/{fileName}?node-id={nodeId} - https://www.figma.com/design/{fileId}/{fileName}?node-id={nodeId}

ワイヤーフレームIDは{fileId}_{nodeId}の形式になります（例: ABC123_2585:942）。