Skip to content

Create Project

Method

REST method is adopted.

HTTP Method

POST: Create project

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 Project

URI

POST /v1/organizations/{organization_id}/projects

Path Parameters

Name Type Required Description
organization_id string Required Organization UUID

Request Body

The request body is JSON.

{
  "name": "My New Project"
}

Request Parameters

Name Type Required Description
name string Required Project name (1-255 characters)

Response

The response is JSON.

{
  "id": "project-uuid",
  "name": "My New Project",
  "organizationId": "org-uuid",
  "codeCount": 0,
  "designCount": 0,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-id",
  "updatedBy": "user-id",
  "deletedBy": null
}

Response Fields

Name Type Description
id string Project UUID
name string Project name
organizationId string Parent organization UUID
codeCount number Number of code entries
designCount number Number of designs
createdAt number Creation timestamp (epoch milliseconds)
updatedAt number Update timestamp (epoch milliseconds)
deletedAt number | null Deletion timestamp (epoch milliseconds)

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 name (empty, too long, etc.) 400 Bad Request
Missing credentials 401 Unauthorized
Insufficient permissions 403 Forbidden
Organization not found 404 Not Found
Internal server error 500 Internal Server Error

Processing Flow

  1. Extract organization ID from path parameters
  2. Extract project name from request body
  3. Verify the user belongs to the organization
  4. In one database transaction, create the project, its initial codebase_index row with status = 'pending', and the creator's user_project assignment with read/write access
  5. Return created project information after the transaction commits

Detailed Flowchart

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

    Service --> AccessCheck[Access Check]
    AccessCheck --> CheckOrg{Organization exists?}
    CheckOrg -->|No| Err404[404 Not Found]
    CheckOrg -->|Yes| CheckPerm{Admin/User<br/>Write permission}

    CheckPerm -->|No| Err404
    CheckPerm -->|Yes| ValidateName{name validation<br/>1-255 chars}

    ValidateName -->|NG| Err400[400 Bad Request]
    ValidateName -->|OK| CreateDB

    CreateDB[DB Create<br/>Transaction] --> GenerateUUID[Generate UUID]
    GenerateUUID --> InsertProject[INSERT project]
    InsertProject --> CreateCodebaseIndex[INSERT codebase_index<br/>status=pending]
    CreateCodebaseIndex --> CreateUserProject[INSERT user_project<br/>project_access=2]

    CreateUserProject --> Refetch[Fetch created record]
    Refetch --> Commit[Commit]
    Commit --> Success[201 Created]

The project is not visible without its one-to-one codebase_index row. A failure in any insert rolls back all three records.