Skip to content

List Users

Method

REST method is adopted.

HTTP Method

GET: List users with pagination and optional organization filter

Naming Convention

To unify naming of query parameters and nodes and improve readability, snake_case is used for URIs and nodes in JSON during requests.

Request and Response

Headers

Meta information is set in HTTP headers rather than in the response body.

Request Headers

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

Response Headers

  • Content-Type: application/json

List Users

URI

/api/v1/users

Query Parameters

Name Type Default Description
page integer 1 Page number for pagination
limit integer 10 Number of items per page (max 100)
sort string updated_at:desc Sort field and direction (format: field:asc or field:desc)
organization_id integer โ€” Filter by organization ID

Response (200 OK)

Response is JSON. 

{
  "currentPage": 1,
  "totalCount": 10,
  "list": [
    {
      "id": 1,
      "cognitoSub": "1111-aaaa-2222-bbbb",
      "organizationId": 1,
      "name": "John Doe",
      "createdAt": 1640995200000,
      "updatedAt": 1640995200000,
      "createdBy": "1111-aaaa-2222-bbbb",
      "updatedBy": "1111-aaaa-2222-bbbb",
      "deletedAt": null,
      "deletedBy": null
    }
  ]
}

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. A valid Bearer token is required in the Authorization header.

Exception Handling

Exception handling status codes are as follows.

Description Status Code Status Name
Missing or invalid token 401 Unauthorized
Internal server error 500 Internal Server Error

Process Flow

Sequence Diagram

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

    Client->>Middleware: GET /api/v1/users
    Middleware->>Middleware: Verify JWT & session

    alt Token Valid
        Middleware-->>API: Auth info
        API->>Service: list({ page, limit, sort, organizationId })
        Service->>DB: findAllPaginated with filters
        DB-->>Service: Paginated user records
        Service-->>API: { currentPage, total, users }
        API-->>Client: 200 OK { currentPage, totalCount, list }
    else Token Invalid
        Middleware-->>Client: 401 Unauthorized
    end

Routes Layer

API routing is performed here. The protectedRoute middleware validates the JWT token. The handler extracts pagination query parameters and optional organization filter, then delegates to the user service.

Source: apps/admin/src/routes/v1/user.ts

Services Layer

This section describes business logic. It calculates the offset from page/limit, then delegates to the repository for paginated retrieval with optional organization filtering.

Source: apps/admin/src/services/user.ts

Repositories Layer

This section describes access to databases. It handles paginated queries with dynamic sorting and optional organization ID filtering.

Source: apps/admin/src/repositories/user.ts

Security

  • Token validated by protectedRoute middleware before handler execution
  • Pagination limit capped at 100 to prevent excessive data retrieval