7.4 KiB

Raw Blame History

📋 ClientsQueryRequestContext - Usage Guide (camelCase)

🎯 Overview

ClientsQueryRequestContext adalah struct yang memudahkan parsing query parameters dari HTTP request untuk filtering clients dengan hierarchy support. Semua JSON fields menggunakan camelCase format.

🔧 Available Query Parameters (camelCase)

Basic Filters

# Filter by name (case-insensitive, partial match)
GET /api/clients?name=company

# Filter by client type
GET /api/clients?clientType=parent_client
GET /api/clients?clientType=sub_client  
GET /api/clients?clientType=standalone

# Filter by parent client ID
GET /api/clients?parentClientId=123e4567-e89b-12d3-a456-426614174000

# Filter by active status
GET /api/clients?isActive=true
GET /api/clients?isActive=false

Hierarchy Filters

# Only show clients that have children (parent clients)
GET /api/clients?onlyParentClients=true

# Only show standalone clients (no parent, no children)
GET /api/clients?onlyStandalone=true

# Only show root level clients (no parent)
GET /api/clients?onlyRootClients=true

# Include all descendants when filtering by parent
GET /api/clients?parentClientId=uuid&includeSubClients=true

Pagination

# Pagination
GET /api/clients?page=1&limit=10
GET /api/clients?page=2&limit=20

# Sorting
GET /api/clients?sort=name&sort_by=asc
GET /api/clients?sort=created_at&sort_by=desc

🚀 Usage Examples (camelCase)

1. Get All Parent Clients

GET /api/clients?clientType=parent_client&isActive=true

2. Get Sub-Clients of Specific Parent

GET /api/clients?parentClientId=123e4567-e89b-12d3-a456-426614174000

3. Get All Root Level Clients

GET /api/clients?onlyRootClients=true

4. Search Clients by Name

GET /api/clients?name=company&isActive=true

5. Get All Standalone Clients

GET /api/clients?onlyStandalone=true

6. Complex Filtering

GET /api/clients?clientType=sub_client&isActive=true&page=1&limit=20&sort=name&sort_by=asc

📊 Response Structure (camelCase)

{
  "success": true,
  "messages": ["Clients list successfully retrieved"],
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Parent Company",
      "description": "Main company",
      "clientType": "parent_client",
      "parentClientId": null,
      "parentClient": null,
      "subClients": [
        {
          "id": "456e7890-e89b-12d3-a456-426614174001",
          "name": "Sub Company 1",
          "clientType": "sub_client",
          "currentUsers": 25,
          "isActive": true
        }
      ],
      "subClientCount": 1,
      "maxUsers": 100,
      "maxStorage": 1073741824,
      "currentUsers": 50,
      "currentStorage": 536870912,
      "settings": "{\"theme\": \"dark\"}",
      "createdById": 1,
      "createdBy": {
        "id": 1,
        "username": "admin",
        "fullname": "Admin User"
      },
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}

🔍 Filter Combinations

Common Use Cases

Dashboard - Show Parent Clients Only

GET /api/clients?onlyParentClients=true&isActive=true&page=1&limit=10

Client Management - Show All Active Clients

GET /api/clients?isActive=true&sort=name&sort_by=asc

Hierarchy View - Show Root Clients

GET /api/clients?onlyRootClients=true&includeSubClients=true

Search - Find Clients by Name

GET /api/clients?name=company&isActive=true

Sub-Client Management - Show Children of Parent

GET /api/clients?parentClientId=uuid&isActive=true

📝 Request Body Examples (camelCase)

Create Client

{
  "name": "New Company",
  "description": "Company description",
  "clientType": "parent_client",
  "parentClientId": null,
  "maxUsers": 100,
  "maxStorage": 1073741824,
  "settings": "{\"theme\": \"dark\"}"
}

Update Client

{
  "name": "Updated Company",
  "clientType": "standalone",
  "parentClientId": null,
  "isActive": true
}

Move Client

{
  "targetParentId": "123e4567-e89b-12d3-a456-426614174000"
}

Bulk Create Sub-Clients

{
  "parentClientId": "123e4567-e89b-12d3-a456-426614174000",
  "subClients": [
    {
      "name": "Sub Client 1",
      "description": "First sub client",
      "maxUsers": 50,
      "maxStorage": 536870912
    },
    {
      "name": "Sub Client 2",
      "description": "Second sub client",
      "maxUsers": 25,
      "maxStorage": 268435456
    }
  ]
}

⚡ Performance Tips

Use specific filters - Always include isActive=true for better performance
Limit results - Use pagination (page & limit) for large datasets
Use hierarchy filters - onlyParentClients, onlyStandalone, onlyRootClients are optimized
Combine filters - Multiple filters work together efficiently

🛠 Implementation Details

Controller Usage

func (_i *clientsController) All(c *fiber.Ctx) error {
    paginate, err := paginator.Paginate(c)
    if err != nil {
        return err
    }

    reqContext := request.ClientsQueryRequestContext{
        Name:              c.Query("name"),
        ClientType:        c.Query("clientType"),
        ParentClientId:    c.Query("parentClientId"),
        IncludeSubClients: c.Query("includeSubClients"),
        OnlyParentClients: c.Query("onlyParentClients"),
        OnlyStandalone:    c.Query("onlyStandalone"),
        OnlyRootClients:   c.Query("onlyRootClients"),
        IsActive:          c.Query("isActive"),
        CreatedById:       c.Query("createdById"),
    }
    req := reqContext.ToParamRequest()
    req.Pagination = paginate

    clientsData, paging, err := _i.clientsService.All(req)
    // ... rest of implementation
}

✅ Testing (camelCase)

Test Cases

# Test basic filtering
curl "http://localhost:8080/api/clients?name=test&isActive=true"

# Test hierarchy filtering  
curl "http://localhost:8080/api/clients?onlyParentClients=true"

# Test pagination
curl "http://localhost:8080/api/clients?page=1&limit=5"

# Test sorting
curl "http://localhost:8080/api/clients?sort=name&sort_by=asc"

# Test complex filtering
curl "http://localhost:8080/api/clients?clientType=sub_client&isActive=true&page=1&limit=10"

🔄 Migration from snake_case

Before (snake_case)

GET /api/clients?client_type=parent_client&parent_client_id=uuid&is_active=true

After (camelCase)

GET /api/clients?clientType=parent_client&parentClientId=uuid&isActive=true

Request Body Migration

// Before
{
  "client_type": "parent_client",
  "parent_client_id": "uuid",
  "max_users": 100,
  "max_storage": 1073741824
}

// After
{
  "clientType": "parent_client",
  "parentClientId": "uuid", 
  "maxUsers": 100,
  "maxStorage": 1073741824
}

🎉 Ready to Use!

ClientsQueryRequestContext sekarang sudah terintegrasi dengan:

✅ Controller parsing (camelCase)
✅ Repository filtering
✅ Swagger documentation (camelCase)
✅ Type safety dengan UUID parsing
✅ Boolean conversion
✅ Pagination support
✅ Full camelCase JSON support

Semua query parameters dan response fields menggunakan camelCase format! 🚀

7.4 KiB Raw Blame History