kontenhumas-be/docs/USERNAME_CHECK_API.md

# Username Check API Documentation

## Overview
API endpoint untuk mengecek apakah username sudah ada atau belum dalam sistem. Endpoint ini hanya mengembalikan status exist/not exist tanpa mengembalikan data user lengkap.

## Endpoint

### Check Username Exists
**GET** `/users/check-username/{username}`

#### Description
Mengecek apakah username sudah ada dalam sistem atau belum.

#### Parameters
- **username** (path, required): Username yang akan dicek keberadaannya

#### Headers
- Tidak memerlukan authentication (public endpoint)

#### Response

##### Success Response (200)
```json
{
  "success": true,
  "messages": ["Username check completed"],
  "data": {
    "username": "john_doe",
    "exists": true
  }
}
```

##### Response Fields
- **username** (string): Username yang dicek
- **exists** (boolean): Status apakah username sudah ada (`true`) atau belum (`false`)

#### Error Responses

##### 500 Internal Server Error
```json
{
  "success": false,
  "messages": ["Database error message"]
}
```

## Usage Examples

### cURL Example
```bash
# Check if username exists
curl -X GET "http://localhost:8080/users/check-username/john_doe"

# Response if username exists
{
  "success": true,
  "messages": ["Username check completed"],
  "data": {
    "username": "john_doe",
    "exists": true
  }
}

# Response if username doesn't exist
{
  "success": true,
  "messages": ["Username check completed"],
  "data": {
    "username": "john_doe",
    "exists": false
  }
}
```

### JavaScript Example
```javascript
const checkUsernameExists = async (username) => {
  try {
    const response = await fetch(`/users/check-username/${username}`, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json'
      }
    });
    
    const data = await response.json();
    
    if (data.success) {
      return data.data.exists;
    } else {
      console.error('Check failed:', data.messages);
      return null;
    }
  } catch (error) {
    console.error('Error checking username:', error);
    return null;
  }
};

// Usage
const usernameExists = await checkUsernameExists('john_doe');
if (usernameExists === true) {
  console.log('Username already exists');
} else if (usernameExists === false) {
  console.log('Username is available');
} else {
  console.log('Error occurred while checking');
}
```

### React Hook Example
```javascript
import { useState, useEffect } from 'react';

const useUsernameCheck = (username) => {
  const [exists, setExists] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    const checkUsername = async () => {
      if (!username || username.length < 3) {
        setExists(null);
        return;
      }

      try {
        setLoading(true);
        setError(null);
        
        const response = await fetch(`/users/check-username/${username}`);
        const data = await response.json();
        
        if (data.success) {
          setExists(data.data.exists);
        } else {
          setError(data.messages[0]);
        }
      } catch (err) {
        setError('Failed to check username');
      } finally {
        setLoading(false);
      }
    };

    // Debounce the check
    const timeoutId = setTimeout(checkUsername, 500);
    return () => clearTimeout(timeoutId);
  }, [username]);

  return { exists, loading, error };
};

// Usage in component
const UsernameInput = () => {
  const [username, setUsername] = useState('');
  const { exists, loading, error } = useUsernameCheck(username);

  return (
    <div>
      <input
        type="text"
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Enter username"
      />
      
      {loading && <span>Checking...</span>}
      {error && <span style={{color: 'red'}}>Error: {error}</span>}
      {exists === true && <span style={{color: 'red'}}>Username already exists</span>}
      {exists === false && <span style={{color: 'green'}}>Username is available</span>}
    </div>
  );
};
```

### Form Validation Example
```javascript
const validateUsername = async (username) => {
  if (!username || username.length < 3) {
    return { valid: false, message: 'Username must be at least 3 characters' };
  }

  if (!/^[a-zA-Z0-9_]+$/.test(username)) {
    return { valid: false, message: 'Username can only contain letters, numbers, and underscores' };
  }

  try {
    const response = await fetch(`/users/check-username/${username}`);
    const data = await response.json();
    
    if (data.success) {
      if (data.data.exists) {
        return { valid: false, message: 'Username already exists' };
      } else {
        return { valid: true, message: 'Username is available' };
      }
    } else {
      return { valid: false, message: 'Unable to check username availability' };
    }
  } catch (error) {
    return { valid: false, message: 'Network error occurred' };
  }
};

// Usage in form submission
const handleSubmit = async (formData) => {
  const usernameValidation = await validateUsername(formData.username);
  if (!usernameValidation.valid) {
    setError(usernameValidation.message);
    return;
  }
  
  // Proceed with form submission
  submitForm(formData);
};
```

## Use Cases
1. **Registration Form**: Mengecek ketersediaan username saat user mendaftar
2. **Real-time Validation**: Validasi username secara real-time saat user mengetik
3. **Username Suggestion**: Memberikan saran username alternatif jika username sudah ada
4. **Profile Update**: Mengecek username baru saat user ingin mengubah username
5. **Admin Panel**: Admin mengecek ketersediaan username untuk user baru

## Performance Considerations
- Endpoint ini tidak memerlukan authentication, sehingga lebih cepat
- Menggunakan query database yang efisien untuk pengecekan keberadaan
- Response yang minimal (hanya status exist/not exist) untuk performa optimal
- Cocok untuk real-time validation dengan debouncing

## Security Notes
- Endpoint ini bersifat public dan tidak memerlukan authentication
- Tidak mengembalikan data sensitif user
- Hanya mengembalikan status boolean exist/not exist
- Username di-validate untuk mencegah injection attacks

## Comparison with Other Endpoints

| Endpoint | Purpose | Authentication | Response |
|----------|---------|----------------|----------|
| `/users/check-username/{username}` | Check username exists | Not required | Boolean status only |
| `/users/username/{username}` | Get user by username | Required | Full user data |
| `/users/info` | Get current user info | Required | Current user data |

## Notes
- Endpoint ini menggunakan method `FindByUsername` dengan `clientId = nil` untuk pencarian global
- Jika terjadi error database, akan mengembalikan error 500
- Username case-sensitive (mengikuti konvensi sistem)
- Cocok untuk digunakan dalam form validation dan real-time checking