Skip to content

List Projects

Method

REST method is adopted.

HTTP Method

GET: Get project list

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

Get List

URI

GET /v1/organizations/{organization_id}/projects

Path Parameters

Name Type Required Description
organization_id string Required Organization UUID

Query Parameters

For list retrieval, page, limit, and sort are generally defined.

Name Type Default Description
page integer 1 Page number (minimum: 1)
limit integer 20 Items per page (minimum: 1, maximum: 100)
sort string asc Sort order (asc or desc)

Response

The response is JSON.

{
  "currentPage": 1,
  "totalCount": 50,
  "list": [
    {
      "id": "project-uuid-1",
      "name": "Project Alpha",
      "organizationId": "org-uuid",
      "codeCount": 15,
      "designCount": 8,
      "createdAt": 1234567890000,
      "updatedAt": 1234567890000,
      "deletedAt": null,
      "createdBy": "user-id",
      "updatedBy": "user-id",
      "deletedBy": null
    }
  ]
}

Response Fields

Name Type Description
currentPage number Current page number
totalCount number Total item count
list array Array of project objects
list[].id string Project UUID
list[].name string Project name
list[].organizationId string Parent organization UUID
list[].codeCount number Number of code entries
list[].designCount number Number of designs
list[].createdAt number Creation timestamp (epoch milliseconds)
list[].updatedAt number Update timestamp (epoch milliseconds)
list[].deletedAt number | null Deletion timestamp (epoch milliseconds)

Authentication

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

Admins with project read permission can list every project in the organization. Regular users only receive projects with an active user_project assignment at read or read/write level.

Error Handling

The status codes for error handling are as follows.

Description Status Code Status Name
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 pagination settings from query parameters
  3. Verify the user belongs to the organization
  4. For a regular user, limit the query to active user_project assignments with read or read/write access
  5. Query projects from the database with pagination
  6. Return paginated response

Detailed Flowchart

flowchart TD
    Start([GET Request]) --> Auth[Auth & Parameter Extraction<br/>page, limit, sort]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Read permission?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| Validate{sort validation}
    Validate -->|NG| Err400[400 Bad Request]
    Validate -->|OK| QueryDB[Repository Layer]
    QueryDB --> CountQuery[Get COUNT]
    CountQuery --> ListQuery[Fetch Records<br/>LIMIT, OFFSET, ORDER BY]
    ListQuery --> Format[Format Response]
    Format --> Success[200 OK<br/>currentPage, totalCount, list]