組織一覧

メソッド

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

HTTP メソッド

GET: 組織の一覧取得

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

Authorization: Bearer <access_token>
Content-Type: application/json

レスポンスヘッダー

Content-Type: application/json

組織一覧

URI

/api/v1/organizations

クエリパラメータ

名前	型	デフォルト	説明
page	integer	1	ページ番号
limit	integer	10	1 ページあたりの件数。最大 100
sort	string	`updated_at:desc`	ソート項目と向き（例: `updated_at:desc`, `created_at:asc`）

レスポンス（200 OK）

レスポンスは JSON です。

{
  "currentPage": 1,
  "totalCount": 5,
  "list": [
    {
      "id": 1,
      "name": "Example Organization",
      "createdAt": 1640995200000,
      "updatedAt": 1640995200000,
      "createdBy": "1111-aaaa-2222-bbbb",
      "updatedBy": "1111-aaaa-2222-bbbb",
      "deletedAt": null,
      "deletedBy": null
    }
  ]
}

認証要件

Amazon Cognito が発行する JSON Web Token（JWT）を用いた認証です。Authorization ヘッダーに有効な Bearer トークンが必要です。

例外処理

例外時のステータスコードは次のとおりです。

説明	ステータスコード	ステータス名
トークンが欠落または無効	401	Unauthorized
サーバ内部エラー	500	Internal Server Error

処理フロー

シーケンス図

sequenceDiagram
    participant Client
    participant Middleware as Protected Route Middleware
    participant API as Hono Router
    participant Service as Organization Service
    participant Repository as Organization Repository
    participant DB as PostgreSQL Database

    Client->>Middleware: GET /api/v1/organizations
    Middleware->>Middleware: Extract Bearer token
    Middleware->>Middleware: Verify JWT & session

    alt Token Valid
        Middleware-->>API: Auth info (sub, adminId)
        API->>Service: list(query)
        Service->>Repository: findAllPaginated(page, limit, sort)
        Repository->>DB: SELECT with pagination
        DB-->>Repository: Organization rows + count
        Repository-->>Service: Paginated result
        Service-->>API: Formatted list response
        API-->>Client: 200 OK { currentPage, totalCount, list }
    else Token Invalid
        Middleware-->>Client: 401 Unauthorized
    end

Routes 層

ルーティングはここで行います。protectedRoute ミドルウェアが JWT とセッションを検証してからハンドラが実行されます。ハンドラはクエリ（page, limit, sort）をデフォルト付きで解析し、組織サービスに委譲します。

ソース: apps/admin/src/routes/v1/organization.ts

Services 層

ビジネスロジックの説明です。解析済みクエリを受け取りデフォルトを適用し、リポジトリ経由でページ分割された組織一覧を取得します。結果を整形し、ページネーション情報とともに返します。

ソース: apps/admin/src/services/organization.ts

Repositories 層

データベースおよび外部サービスへのアクセスです。パラメータ化された SQL で ORDER BY / LIMIT / OFFSET を用いてページ分割取得し、総件数は COUNT で取得します。

ソース: apps/admin/src/repositories/organization.ts

セキュリティ

ハンドラ実行前に protectedRoute ミドルウェアがトークンを検証します
verifySession によりセッションの存在を確認します
クエリ値はサニタイズされ、インジェクションを防ぎます