Skip to content

Create Code

Method

REST method is adopted.

HTTP Method

POST: Create code

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: multipart/form-data
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Create Code

URI

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

Path Parameters

Name Type Required Description
organization_id number Required Backend PostgreSQL organization ID
project_id number Required Backend PostgreSQL project ID

Request Body

The request body is multipart/form-data.

Form Fields

Name Type Required Description
id string Optional Code UUID. Omit to let the backend generate one
name string Required Code name (1-255 characters)
source_code string Required Code source code
css_code string Optional Code CSS code
file File Required Preview image (PNG/JPG/JPEG/GIF, max 5MB)

Response

The response is JSON (HTTP status: 201 Created).

{
  "id": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
  "projectId": 42,
  "name": "Button",
  "s3Key": "code/0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b.png",
  "sourceCode": "const Button = () => { ... }",
  "cssCode": ".button { ... }",
  "status": 2,
  "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

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 code UUID or missing required fields 400 Bad Request
Missing credentials 401 Unauthorized
Insufficient permissions 403 Forbidden
Project or organization not found 404 Not Found
File size exceeds limit 413 Payload Too Large
Internal server error 500 Internal Server Error

Processing Flow

  1. Extract all fields from form data
  2. Generate a code UUID when id is omitted, or validate the supplied UUID
  3. Validate file type and size
  4. Upload image to S3
  5. Create code record in PostgreSQL
  6. Send code-import processing message to SQS with organization_id, project_id, code_id, source/CSS, and preview image URL
  7. Return created code information

Detailed Flowchart

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[Get Auth Info<br/>JWT from Cognito]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[Access Check]
    AccessCheck --> CheckOrg{Org & Project<br/>exist?}
    CheckOrg -->|No| Err404[404 Not Found]
    CheckOrg -->|Yes| CheckPerm{Admin/User<br/>Write permission}
    CheckPerm -->|No| Err404
    CheckPerm -->|Yes| Validate

    Validate[Input Validation] --> ValidName{name<br/>1-255 chars}
    ValidName -->|NG| Err400[400 Bad Request]
    ValidName -->|OK| ValidCode{sourceCode<br/>required}
    ValidCode -->|NG| Err400
    ValidCode -->|OK| ValidImg{image<br/>type/size}
    ValidImg -->|NG| Err400
    ValidImg -->|OK| CheckExist

    CheckExist[Check Existing Code] --> Exists{Exists?}
    Exists -->|Active| Err400
    Exists -->|Deleted| Process[Process]
    Exists -->|No| Process

    Process --> S3Upload[S3 Image Upload]
    S3Upload --> S3OK{Successful?}
    S3OK -->|NG| Err400
    S3OK -->|OK| SQSSend[Send SQS Message<br/>Fail-Fast Pattern]

    SQSSend --> SQSOK{Successful?}
    SQSOK -->|NG| Err500[500 SQS Unavailable<br/>DB operation aborted]
    SQSOK -->|OK| DBOp{Deleted existing?}

    DBOp -->|Yes| Restore[DB Restore<br/>deletedAt=NULL]
    DBOp -->|No| Create[DB Create new]

    Restore --> Success[201 Created]
    Create --> Success

Code ID Format

The code ID is the backend PostgreSQL code UUID. It is the same value sent to AI v2 as code_id, stored in DocumentDB as code._id, and echoed in the code-import webhook as recordId.

Examples: - Valid: 0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b - Invalid: not-a-uuid, Button