Skip to content

Create Wireframe

Method

REST method is adopted.

HTTP Method

POST: Create wireframe (import from Figma URL)

Naming Convention

To unify the naming of query parameters and nodes and improve readability, snake_case is used for URIs and JSON nodes in requests.

Request and Response

Headers

Meta information is set in HTTP headers, not in the response body.

Request Headers

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

Response Headers

  • Content-Type

Create Wireframe

URI

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

Path Parameters

Name Type Required Description
organization_id integer Required Organization ID
project_id integer Required Project ID

Request Body

The request body is JSON.

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

Request Parameters

Name Type Required Description
figma_url string Required Figma URL (file or design)

Response

The response is JSON (HTTP status: 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
}

Status Values

Value Description
0 Pending
1 Processing
2 Completed
3 Failed

Response Fields

Name Type Description
id string Wireframe ID (format: fileId_nodeId)
projectId number Project ID
s3Key string | null S3 object key (set after processing completes)
frameName string | null Figma frame name (set after processing completes)
status number Processing status (0-3)
createdAt number Creation timestamp (epoch milliseconds)
updatedAt number Update timestamp (epoch milliseconds)
deletedAt number | null Deletion timestamp (epoch milliseconds); null if not deleted
createdBy string Creator user ID
updatedBy string Updater user ID
deletedBy string | null Deleter user ID; null if not deleted

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito.

Error Handling

The status codes for error handling are as follows.

Description Status Code Status Name
Invalid Figma URL format 400 Bad Request
Missing credentials 401 Unauthorized
Insufficient permissions 403 Forbidden
Project or organization not found 404 Not Found
Internal server error 500 Internal Server Error

Processing Flow

  1. Parse the Figma URL to extract fileId and nodeId
  2. Retrieve the user's Figma PAT
  3. Fetch wireframe data and image from the Figma API (parallel)
  4. Upload image and JSON schema to S3 (parallel)
  5. Send processing message to SQS
  6. Create wireframe record in the database
  7. Return response with initial status 0 (pending)

Detailed Flowchart

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Write permission?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| ParseURL[Parse Figma URL]

    ParseURL --> ValidURL{Valid URL?}
    ValidURL -->|NG| Err400[400 Bad Request]
    ValidURL -->|OK| GetToken[Get Figma PAT]

    GetToken --> HasToken{Token exists?}
    HasToken -->|No| Err400
    HasToken -->|Yes| ParallelFetch[Parallel Figma API Calls]

    ParallelFetch --> FetchImage[Fetch Figma Image]
    ParallelFetch --> FetchSchema[Fetch Wireframe Data]

    FetchImage --> ParallelS3[Parallel S3 Upload]
    FetchSchema --> ParallelS3

    ParallelS3 --> UploadImage[Upload Image]
    ParallelS3 --> UploadJSON[Upload JSON]

    UploadImage --> CheckUploads{Upload successful?}
    UploadJSON --> CheckUploads

    CheckUploads -->|NG| Err500[500 Internal Error]
    CheckUploads -->|OK| SQSSend[Send SQS Message]

    SQSSend --> SQSOK{Successful?}
    SQSOK -->|NG| Err500
    SQSOK -->|OK| CreateDB[Create DB Record<br/>status=0 pending]

    CreateDB --> Success[201 Created<br/>Async processing started]

Asynchronous Processing

Wireframes are processed asynchronously. A background worker updates the status: - 0 (pending) โ†’ 1 (processing) โ†’ 2 (completed) or 3 (failed)

Figma URL Format

Valid Figma URL formats: - https://www.figma.com/file/{fileId}/{fileName}?node-id={nodeId} - https://www.figma.com/design/{fileId}/{fileName}?node-id={nodeId}

The wireframe ID will be in the format {fileId}_{nodeId} (e.g., ABC123_2585:942).