コンテンツにスキップ

デザイン作成

メソッド

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

HTTPメソッド

POST: デザイン作成（Figma URLからインポート）

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

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

レスポンスヘッダー

  • Content-Type

デザイン作成

URI

POST /v1/organizations/{organization_id}/projects/{project_id}/designs

パスパラメータ

名前 型 必須 説明
organization_id number 必須 backend PostgreSQL organization ID
project_id number 必須 backend PostgreSQL project 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": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "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（形式: {project_id}_{file_id}_{node_id}）
projectId number backend PostgreSQL project ID
s3Key string | null S3オブジェクトキー（処理完了後）
frameName string | null Figmaフレーム名（処理完了後）
status number 処理ステータス（0-3）
createdAt number 作成日時（エポックミリ秒）
updatedAt number 更新日時（エポックミリ秒）

認証

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

例外処理

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

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

処理フロー

  1. Figma URLをパースしてfileIdとnodeIdを抽出
  2. project の dedicated codebase_index row を読み、completed を要求して stable codebase_index_url を解決
  3. ユーザーのFigma PATを取得
  4. Figma APIからデザインデータと画像を取得（並行処理）
  5. 画像と required JSON schema をS3にアップロード（並行処理）
  6. design row を作成し、authoritative source timestamp と request token から sortable source_order を生成
  7. organization_id、project_id、design_id、design_name、file_id、node_id、img_url、required json_schema_url、source_order、stable codebase_index_url を含む design-import message を SQS に送る。figma_url と expected bundle token/hash は含めない
  8. 初期ステータス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| CheckIndex[dedicated codebase_index を読む]

    CheckIndex --> IndexReady{Completed with current URL?}
    IndexReady -->|No| Err409[409 CODEBASE_INDEX_NOT_READY]
    IndexReady -->|Yes| 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| CreateDB[DBレコード作成<br/>status=0 pending + source_order]

    CreateDB --> SQSSend[SQSメッセージ送信<br/>codebase_index_url 付き]

    SQSSend --> SQSOK{成功?}
    SQSOK -->|NG| Err500
    SQSOK -->|OK| 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は {project_id}_{file_id}_{node_id} の形式になります（例: 42_hDDA9BNori9OTXSClduXqR_40002029:37033）。Figma node ID を含みます。