コンテンツにスキップ

プロジェクト一覧

メソッド

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

HTTPメソッド

GET: プロジェクトリスト取得

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

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

レスポンスヘッダー

  • Content-Type

リスト取得

URI

GET /v1/organizations/{organization_id}/projects

パスパラメータ

名前 型 必須 説明
organization_id string 必須 組織UUID

クエリパラメータ

リスト取得では、基本的にpage、limit、sortが定義されます。

名前 型 デフォルト 説明
page integer 1 ページ番号（最小: 1）
limit integer 20 ページあたりのアイテム数（最小: 1、最大: 100）
sort string asc ソート順序（asc または desc）

レスポンス

レスポンスは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
    }
  ]
}

レスポンスフィールド

名前 型 説明
currentPage number 現在のページ番号
totalCount number 総アイテム数
list array プロジェクトオブジェクトの配列
list[].id string プロジェクトUUID
list[].name string プロジェクト名
list[].organizationId string 親組織UUID
list[].codeCount number コード数
list[].designCount number デザイン数
list[].createdAt number 作成日時（エポックミリ秒）
list[].updatedAt number 更新日時（エポックミリ秒）
list[].deletedAt number | null 削除日時（エポックミリ秒）

認証

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

プロジェクトの読み取り権限を持つ管理者は組織内の全プロジェクトを取得できます。一般ユーザーには、読み取りまたは読み取り・書き込みレベルの有効な user_project 割り当てがあるプロジェクトのみ返されます。

例外処理

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

説明 ステータスコード ステータス名
認証情報不足 401 Unauthorized
実行権限不足 403 Forbidden
組織が見つかりません 404 Not Found
内部サーバーエラー 500 Internal Server Error

処理フロー

  1. パスパラメータから組織IDを抽出
  2. クエリパラメータからページネーション設定を抽出
  3. ユーザーが組織に属していることを検証
  4. 一般ユーザーの場合、読み取りまたは読み取り・書き込み権限の有効な user_project 割り当てに限定
  5. ページネーション付きでデータベースからプロジェクトをクエリ
  6. ページネーション付きレスポンスを返却

詳細フローチャート

flowchart TD
    Start([GET Request]) --> Auth[認証・パラメータ取得<br/>page, limit, sort]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[権限チェック]
    AccessCheck --> HasAccess{Read権限?}
    HasAccess -->|なし| Err404[404 Not Found]
    HasAccess -->|あり| Validate{sort検証}
    Validate -->|NG| Err400[400 Bad Request]
    Validate -->|OK| QueryDB[Repository Layer]
    QueryDB --> CountQuery[COUNT取得]
    CountQuery --> ListQuery[レコード取得<br/>LIMIT, OFFSET, ORDER BY]
    ListQuery --> Format[レスポンス整形]
    Format --> Success[200 OK<br/>currentPage, totalCount, list]