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)

{
  "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

{
  "success": false,
  "messages": ["Database error message"]
}

Usage Examples

cURL Example

# 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

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

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

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