Dokumentasi API TeamTalk 5 v1.0

A. Pendahuluan & Autentikasi API

1. Pendahuluan

2. Base URL

• Development (sesuai konfigurasi composer.json): http://localhost:8080/api
• Production: https://domain-kamu.com/api (sesuaikan dengan domain deployment kamu)

3. Autentikasi

• Header Name: X-API-Key
• Cara Mendapatkan API Key: API Key dikonfigurasi di sisi server dalam file src/settings.php pada variabel $apiKey. Untuk lingkungan produksi, pastikan nilai ini diubah menjadi key yang kuat dan acak, dan idealnya dikelola melalui environment variables server.

curl -X GET "http://localhost:8080/api/users/online" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: NILAI_API_KEY_KAMU"
        

4. Format Request

• Content-Type: Untuk request yang mengirimkan data dalam body (misalnya, POST, PUT), header Content-Type harus disetel ke application/json.
• Metode HTTP: API ini menggunakan metode HTTP standar:
  • GET: Untuk mengambil resource.
  • POST: Untuk membuat resource baru.
  • PUT: Untuk memperbarui resource yang sudah ada secara keseluruhan atau sebagian (tergantung implementasi endpoint).
  • DELETE: Untuk menghapus resource.

5. Format Respons Sukses

{
    "status": "success",
    "message": "Operasi berhasil.", // Opsional, tergantung endpoint
    "data": {
        // ... data spesifik yang dikembalikan oleh endpoint ...
    }
}
        

{
    "status": "success",
    "message": "Channel 'Nama Channel Baru' created successfully.",
    "data": {
        "id": 123, // ID resource yang baru dibuat
        "name": "Nama Channel Baru",
        // ... detail lain dari resource yang baru dibuat ...
    }
}
        

{
    "status": "success",
    "data": {
        "accounts": [
            { "username": "user1", "userType": 1, /* ... */ },
            { "username": "user2", "userType": 2, /* ... */ }
        ],
        "count": 2
    }
}
        

6. Format Respons Error Umum

{
    "error_type": "TipeErrorSpesifik",
    "message": "Deskripsi error yang mudah dipahami."
}
        

{
    "error_type": "TipeErrorSpesifik",
    "message": "Deskripsi error yang mudah dipahami.",
    "details": {
        "exception_class": "NamaKelasException",
        "code": 0, // Kode exception
        "file": "/path/to/file.php",
        "line": 123,
        "trace": [ /* ... stack trace ... */ ] // Hanya untuk error 5xx atau jika bukan HttpException
    }
}
        

• 401 Unauthorized (API Key tidak valid atau hilang):

  
  {
      "error_type": "Unauthorized",
      "message": "API Key is missing."
  }
                  

  atau

  
  {
      "error_type": "Unauthorized",
      "message": "Invalid API Key."
  }
                  

• 400 Bad Request (Input tidak valid):

  
  {
      "error_type": "BadRequest",
      "message": "Invalid input provided. Username: Username is required and cannot be empty."
  }
                  

• 403 Forbidden (Aksi tidak diizinkan):

  
  {
      "error_type": "Forbidden",
      "message": "Deleting the API administrator account is not allowed."
  }
                  

• 404 Not Found (Endpoint atau resource tidak ditemukan):

  
  {
      "error_type": "NotFound",
      "message": "The requested endpoint was not found on this server."
  }
                  

  atau (jika resource spesifik tidak ditemukan)

  
  {
      "error_type": "NotFound",
      "message": "User account 'username_tidak_ada' not found."
  }
                  

• 405 Method Not Allowed (Metode HTTP salah untuk endpoint):

  
  {
      "error_type": "MethodNotAllowed",
      "message": "Method Not Allowed. Must be one of: GET, POST", // Pesan bisa bervariasi
      "allowed_methods": ["GET", "POST"]
  }
                  

• 409 Conflict (Resource sudah ada saat mencoba membuat):

  
  {
      "error_type": "HttpError", // Bisa juga dikustomisasi di JsonErrorRenderer menjadi "Conflict"
      "message": "Channel 'Nama Channel' (or a channel with the same properties at that location) already exists."
  }
                  

• 500 Internal Server Error (Error tidak terduga di server):

  
  {
      "error_type": "InternalServerError",
      "message": "An unexpected internal error occurred."
  }
                  

• 503 Service Unavailable (Error koneksi atau login ke server TeamTalk):

  
  {
      "error_type": "HttpError", // JsonErrorRenderer akan mengklasifikasikannya sebagai HttpError jika tidak spesifik
      "message": "Failed to connect to TeamTalk server." // Pesan bisa bervariasi
  }
                  

7. Catatan Penting

• Keamanan API Key: Jaga kerahasiaan API Key kamu. Jangan pernah mengeksposnya di sisi klien (frontend JavaScript, aplikasi mobile, dll.). API ini dimaksudkan untuk digunakan dari backend ke backend.
• Mode Produksi: Untuk lingkungan produksi, pastikan displayErrorDetails disetel ke false dalam konfigurasi server (src/settings.php) untuk mencegah kebocoran informasi sensitif.
• Logging: Server API mencatat aktivitas dan error ke file log (biasanya logs/app.log). Periksa log ini untuk debugging jika terjadi masalah.

B. Endpoint Pengguna (Users)

1. Mendapatkan Daftar Pengguna Online

• Endpoint: GET /users/online
• Metode: GET
• Deskripsi: Mengambil daftar semua pengguna yang saat ini sedang online di server TeamTalk. Informasi yang dikembalikan mencakup nickname pengguna dan path channel tempat mereka berada.
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Disarankan, meskipun GET tidak memiliki body)

curl -X GET "http://localhost:8080/api/users/online" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json"
        

{
    "status": "success",
    "data": {
        "users": [
            {
                "nickname": "UserSatu",
                "channel": "/Lobby Utama/Ruang Diskusi"
            },
            {
                "nickname": "AdminServer",
                "channel": "/"
            },
            {
                "nickname": "PemainGame",
                "channel": "/Gaming Zone/Game A"
            },
            {
                "nickname": "TT5ClientAPI",
                "channel": "N/A (API Client)"
            }
        ],
        "count": 4
    }
}
        

• nickname (string): Nickname pengguna yang sedang online.
• channel (string): Path lengkap dari channel tempat pengguna berada.
  • Jika pengguna berada di root channel, nilainya adalah /.
  • Jika pengguna adalah API client itu sendiri (sesuai nickname di konfigurasi), nilainya bisa N/A (API Client).
  • Jika ada error resolusi path channel, pesan error akan ditampilkan di sini (misalnya, In Channel ID: 123 (Path Resolution Error)).

• 401 Unauthorized:

  
  {
      "error_type": "Unauthorized",
      "message": "API Key is missing." // atau "Invalid API Key."
  }
                  

• 503 Service Unavailable: Jika terjadi masalah saat API mencoba terhubung atau login ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk service interaction error: Failed to connect to TeamTalk server."
  }
                  

  atau

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk service interaction error: Failed to login to TeamTalk server with API credentials."
  }
                  

  (Pesan message bisa bervariasi tergantung pada detail error dari TeamTalkClientException)

C. Endpoint Akun (Accounts)

1. Membuat atau Memperbarui Akun Pengguna

• Endpoint: POST /accounts
• Metode: POST
• Deskripsi: Membuat akun pengguna baru di server TeamTalk. Jika akun dengan username yang sama sudah ada, perilaku server TeamTalk (melalui perintah newaccount) mungkin akan menimpa akun tersebut (termasuk passwordnya). API ini saat ini tidak secara eksplisit membedakan antara "create" dan "update password" melalui endpoint ini; perintah newaccount yang dikirim ke server akan diproses apa adanya.
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

{
    "username": "penggunabaru",
    "password": "PasswordKuat123!"
}
        

• username (string, wajib): Username untuk akun baru. Tidak boleh kosong.
• password (string, wajib): Password untuk akun baru. Tidak boleh kosong.

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Wajib)

curl -X POST "http://localhost:8080/api/accounts" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json" \
     -d '{
           "username": "penggunabaru",
           "password": "PasswordKuat123!"
         }'
        

{
    "status": "success",
    "message": "User account 'penggunabaru' processed successfully (created or updated).",
    "data": {
        "username": "penggunabaru"
    }
}
        

• 400 Bad Request: Jika input tidak valid (misalnya, username atau password kosong).

  
  {
      "error_type": "BadRequest",
      "message": "Invalid input provided. Username: Username is required and cannot be empty."
  }
                  

  atau

  
  {
      "error_type": "BadRequest",
      "message": "Invalid request body. Expected JSON object."
  }
                  

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 503 Service Unavailable: Jika terjadi masalah saat API mencoba terhubung, login, atau memproses perintah ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Failed to create user account 'penggunabaru': [Error Code dari TeamTalk] Pesan error dari TeamTalk"
  }
                  

  (Pesan message akan mencerminkan error spesifik dari TeamTalkClientException)

2. Mendapatkan Daftar Semua Akun Pengguna

• Endpoint: GET /accounts
• Metode: GET
• Deskripsi: Mengambil daftar semua akun pengguna yang terdaftar di server TeamTalk.
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Disarankan)

curl -X GET "http://localhost:8080/api/accounts" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json"
        

{
    "status": "success",
    "data": {
        "accounts": [
            {
                "username": "admin",
                "userType": 2, // 1 = Default, 2 = Admin
                "note": "Akun administrator utama",
                "initialChannel": "/Lobby Utama"
            },
            {
                "username": "penggunabaru",
                "userType": 1,
                "note": "",
                "initialChannel": ""
            },
            {
                "username": "InfiArtt", // Akun yang digunakan API untuk login
                "userType": 2,
                "note": "",
                "initialChannel": ""
            }
        ],
        "count": 3
    }
}
        

• username (string): Username akun.
• userType (integer): Tipe pengguna (biasanya 1 untuk pengguna default, 2 untuk administrator).
• note (string): Catatan yang terkait dengan akun (jika ada).
• initialChannel (string): Path channel awal tempat pengguna akan ditempatkan saat login (jika dikonfigurasi).

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 503 Service Unavailable: Jika terjadi masalah saat API mencoba terhubung atau login ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Error listing user accounts: Pesan error dari TeamTalk"
  }
                  

3. Menghapus Akun Pengguna

• Endpoint: DELETE /accounts/{username}
• Metode: DELETE
• Deskripsi: Menghapus akun pengguna dari server TeamTalk berdasarkan username.
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

• username (string, wajib): Username dari akun yang akan dihapus. Penting: URL encoding mungkin diperlukan jika username mengandung karakter khusus (meskipun umumnya username tidak demikian).

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Disarankan)

curl -X DELETE "http://localhost:8080/api/accounts/penggunayangakandihapus" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json"
        

{
    "status": "success",
    "message": "User account 'penggunayangakandihapus' deleted successfully."
}
        

• 400 Bad Request: Jika username tidak disertakan dalam path.

  
  {
      "error_type": "BadRequest",
      "message": "Username parameter is required."
  }
                  

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 403 Forbidden: Jika mencoba menghapus akun yang digunakan oleh API itu sendiri untuk login ke TeamTalk (sesuai konfigurasi teamtalk_server.username di settings.php).

  
  {
      "error_type": "Forbidden",
      "message": "Deleting the API administrator account is not allowed."
  }
                  

• 404 Not Found: Jika akun dengan username yang diberikan tidak ditemukan di server TeamTalk.

  
  {
      "error_type": "NotFound",
      "message": "User account 'username_tidak_ada' not found."
  }
                  

• 503 Service Unavailable: Jika terjadi masalah lain saat API mencoba terhubung, login, atau memproses perintah ke server TeamTalk (selain akun tidak ditemukan).

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Pesan error dari TeamTalk selain 'not found'"
  }
                  

D. Endpoint Channel (Channels)

1. Membuat Channel Baru

• Endpoint: POST /channels
• Metode: POST
• Deskripsi: Membuat channel baru di server TeamTalk. Channel baru akan dibuat sebagai sub-channel dari parentPath yang ditentukan, atau di bawah root server jika parentPath tidak diberikan atau kosong.
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

{
    "name": "Ruang Diskusi Baru",
    "parentPath": "/Lobby Utama", // Opsional, default ke root server (ID 1)
    "password": "passchannelrahasia", // Opsional, default ke tanpa password
    "topic": "Topik diskusi untuk channel ini.", // Opsional, default ke kosong
    "operatorPassword": "oppasschannel", // Opsional, default ke tanpa operator password
    "audioBitrateKbps": 64, // Opsional, default ke 64. Pilihan: 16, 32, 64, 96, 128, 192, 256, 320
    "audioChannels": "mono", // Opsional, default ke "mono". Pilihan: "mono", "stereo"
    "audioApplication": "voip" // Opsional, default ke "voip". Pilihan: "voip", "music"
}
        

• name (string, wajib): Nama untuk channel baru. Tidak boleh kosong.
• parentPath (string, opsional): Path lengkap dari channel induk tempat channel baru akan dibuat.
  • Contoh: /Lobby Utama/Sub Ruang.
  • Jika tidak diberikan, kosong (""), atau /, channel akan dibuat di bawah root server (induknya adalah channel ID 1).
• password (string, opsional): Password untuk masuk ke channel. Defaultnya tidak ada password.
• topic (string, opsional): Topik atau deskripsi channel. Defaultnya kosong.
• operatorPassword (string, opsional): Password operator untuk channel. Defaultnya tidak ada operator password.
• audioBitrateKbps (integer, opsional): Bitrate audio (OPUS) dalam Kbps. Default: 64. Nilai yang diizinkan: 16, 32, 64, 96, 128, 192, 256, 320.
• audioChannels (string, opsional): Jumlah channel audio. Default: "mono". Pilihan: "mono", "stereo".
• audioApplication (string, opsional): Jenis aplikasi audio (OPUS). Default: "voip". Pilihan: "voip", "music".

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Wajib)

curl -X POST "http://localhost:8080/api/channels" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Channel Baru di Root",
           "topic": "Channel untuk tes"
         }'
        

curl -X POST "http://localhost:8080/api/channels" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Sub Diskusi",
           "parentPath": "/Channel Baru di Root",
           "audioBitrateKbps": 96,
           "audioChannels": "stereo"
         }'
        

{
    "status": "success",
    "message": "Channel 'Ruang Diskusi Baru' created successfully.",
    "data": {
        "id": 125, // ID channel yang baru dibuat
        "name": "Ruang Diskusi Baru",
        "parentIdUsed": 10, // ID channel induk yang digunakan (hasil resolusi parentPath)
        "topic": "Topik diskusi untuk channel ini.",
        "audioBitrateKbpsUsed": 64,
        "audioChannelsUsed": "mono",
        "audioApplicationUsed": "voip"
    }
}
        

• 400 Bad Request: Jika input tidak valid (misalnya, name kosong, parentPath tidak ditemukan, atau nilai audio tidak valid).

  
  {
      "error_type": "BadRequest",
      "message": "Invalid input provided. Channel name: Channel name is required and cannot be empty."
  }
                  

  atau

  
  {
      "error_type": "BadRequest",
      "message": "Parent channel path '/PathTidakAda' not found."
  }
                  

  atau

  
  {
      "error_type": "BadRequest",
      "message": "Invalid input provided. audioBitrateKbps: Invalid audioBitrateKbps. Allowed: 16, 32, 64, 96, 128, 192, 256, 320."
  }
                  

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 409 Conflict: Jika channel dengan nama yang sama sudah ada di bawah parent yang sama, atau ada konflik lain yang dilaporkan oleh server TeamTalk (misalnya, error [3004] Channel already exists).

  
  {
      "error_type": "HttpError",
      "message": "Channel 'Ruang Diskusi Baru' (or a channel with the same properties at that location) already exists."
  }
                  

• 503 Service Unavailable: Jika terjadi masalah saat API mencoba terhubung, login, atau memproses perintah ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Pesan error spesifik dari TeamTalkClientException"
  }
                  

2. Mendapatkan Daftar Semua Channel

• Endpoint: GET /channels
• Metode: GET
• Deskripsi: Mengambil daftar semua channel yang ada di server TeamTalk, beserta struktur hierarkinya (melalui parentId dan path).
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Disarankan)

curl -X GET "http://localhost:8080/api/channels" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json"
        

{
    "status": "success",
    "data": {
        "channels": [
            {
                "id": 1,
                "name": "NamaServerTeamTalkKamu", // Nama root channel biasanya nama server
                "topic": "Message of the Day server",
                "parentId": 0,
                "path": "/"
            },
            {
                "id": 10,
                "name": "Lobby Utama",
                "topic": "Selamat datang di lobby",
                "parentId": 1,
                "path": "/Lobby Utama"
            },
            {
                "id": 125,
                "name": "Ruang Diskusi Baru",
                "topic": "Topik diskusi untuk channel ini.",
                "parentId": 10,
                "path": "/Lobby Utama/Ruang Diskusi Baru"
            }
        ],
        "count": 3
    }
}
        

• id (integer): ID unik channel.
• name (string): Nama channel.
• topic (string): Topik atau deskripsi channel.
• parentId (integer): ID dari channel induk. Untuk root channel (biasanya ID 1), parentId adalah 0.
• path (string): Path lengkap channel dari root.

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 503 Service Unavailable: Jika terjadi masalah saat API mencoba terhubung atau login ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Pesan error dari TeamTalkClientException"
  }
                  

3. Menghapus Channel

• Endpoint: DELETE /channels/{id}
• Metode: DELETE
• Deskripsi: Menghapus channel dari server TeamTalk berdasarkan ID channel. Channel tidak dapat dihapus jika masih berisi sub-channel atau pengguna (tergantung konfigurasi server TeamTalk).
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

• id (integer, wajib): ID dari channel yang akan dihapus.

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Disarankan)

curl -X DELETE "http://localhost:8080/api/channels/125" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json"
        

{
    "status": "success",
    "message": "Channel ID 125 deleted successfully."
}
        

• 400 Bad Request:
  • Jika id bukan angka atau 0.

    
    {
        "error_type": "BadRequest",
        "message": "Channel ID parameter is invalid."
    }
                            

  • Jika mencoba menghapus channel yang tidak kosong (error dari TeamTalk [3006] channel is not empty).

    
    {
        "error_type": "BadRequest",
        "message": "Channel ID 125 cannot be deleted because it is not empty. Server message: [3006] Channel is not empty"
    }
                            

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 403 Forbidden: Jika mencoba menghapus root channel utama (ID 1).

  
  {
      "error_type": "Forbidden",
      "message": "Deleting the main root channel (ID 1) is not allowed."
  }
                  

• 404 Not Found: Jika channel dengan id yang diberikan tidak ditemukan di server TeamTalk (error dari TeamTalk [3005] Channel not found).

  
  {
      "error_type": "NotFound",
      "message": "Channel ID 120 tidak ditemukan." // Pesan dari API
  }
                  

• 503 Service Unavailable: Jika terjadi masalah lain saat API mencoba terhubung, login, atau memproses perintah ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Pesan error lain dari TeamTalkClientException"
  }
                  

4. Memperbarui Channel

• Endpoint: PUT /channels/{id}
• Metode: PUT
• Deskripsi: Memperbarui properti dari channel yang sudah ada berdasarkan ID-nya. Hanya parameter yang disertakan dalam body request yang akan dipertimbangkan untuk pembaruan.
• Autentikasi: Memerlukan API Key (lihat A.3. Autentikasi).

• id (integer, wajib): ID dari channel yang akan diperbarui.

{
    "name": "Nama Channel Diperbarui", // Opsional
    "topic": "Topik channel yang baru.", // Opsional
    "password": "passchannelbaru", // Opsional, kirim string kosong "" untuk menghapus password
    "operatorPassword": "oppassbaru", // Opsional, kirim string kosong "" untuk menghapus op password
    "audioBitrateKbps": 128, // Opsional
    "audioChannels": "stereo", // Opsional
    "audioApplication": "music" // Opsional
}
        

• name (string): Nama baru untuk channel. Tidak boleh string kosong jika diberikan.
• topic (string): Topik atau deskripsi baru channel.
• password (string): Password baru untuk channel. Kirim string kosong ("") untuk menghapus password yang ada.
• operatorPassword (string): Password operator baru untuk channel. Kirim string kosong ("") untuk menghapus password operator yang ada.
• audioBitrateKbps (integer): Bitrate audio baru. Nilai yang diizinkan: 16, 32, 64, 96, 128, 192, 256, 320.
• audioChannels (string): Jumlah channel audio baru. Pilihan: "mono", "stereo".
• audioApplication (string): Jenis aplikasi audio baru. Pilihan: "voip", "music".

• Mengubah parentid (memindahkan channel) tidak didukung melalui endpoint ini.
• Mengubah type channel (permanent/temporary) juga tidak didukung saat ini melalui endpoint ini (akan memerlukan penyesuaian di TeamTalkClient).
• Mengirim body request kosong ({}) atau body dengan parameter yang tidak valid/tidak diizinkan akan menghasilkan error 400 Bad Request.

• X-API-Key: NILAI_API_KEY_KAMU (Wajib)
• Content-Type: application/json (Wajib)

curl -X PUT "http://localhost:8080/api/channels/10" \
     -H "X-API-Key: kweW^^4345jfvzXeddduuww" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Lobby Utama (Updated)",
           "topic": "Selamat datang di lobby yang sudah diperbarui!",
           "audioBitrateKbps": 96
         }'
        

{
    "status": "success",
    "message": "Channel ID 10 updated successfully.",
    "data": {
        "id": 10,
        "name": "Lobby Utama (Updated)",
        "topic": "Selamat datang di lobby yang sudah diperbarui!",
        "parentId": 1,
        "path": "/Lobby Utama (Updated)", // Path juga akan terupdate jika nama berubah
        // ... field lain dari channel yang mungkin terpengaruh oleh update audio ...
    }
}
        

• 400 Bad Request:
  • Jika id bukan angka atau 0.

    
    {
        "error_type": "BadRequest",
        "message": "Channel ID parameter is invalid."
    }
                            

  • Jika body request tidak valid (bukan JSON, kosong, atau parameter tidak valid).

    
    {
        "error_type": "BadRequest",
        "message": "Invalid request body. Expected JSON object with parameters to update."
    }
                            

    atau

    
    {
        "error_type": "BadRequest",
        "message": "Request body is empty. No parameters to update."
    }
                            

    atau

    
    {
        "error_type": "BadRequest",
        "message": "Invalid input provided for update. audioBitrateKbps: Invalid audioBitrateKbps. Allowed: ..."
    }
                            

  • Jika mencoba melakukan operasi yang tidak diizinkan oleh TeamTalkClient (misalnya, mengubah parentid atau chanid yang dilempar sebagai exception oleh client).

    
    {
        "error_type": "BadRequest",
        "message": "Update failed: Changing 'parentid' is not supported via this update method. Use a specific 'move' operation if available."
    }
                            

• 401 Unauthorized: (Lihat A.6. Format Respons Error Umum)
• 404 Not Found: Jika channel dengan id yang diberikan tidak ditemukan di server TeamTalk (error dari TeamTalk [3005] Channel not found).

  
  {
      "error_type": "NotFound",
      "message": "Channel ID 120 not found for update."
  }
                  

• 503 Service Unavailable: Jika terjadi masalah lain saat API mencoba terhubung, login, atau memproses perintah ke server TeamTalk.

  
  {
      "error_type": "HttpError",
      "message": "TeamTalk Service Error: Pesan error lain dari TeamTalkClientException"
  }
                  

E. Catatan untuk Pengembang

1. TeamTalkClient.php (Inti Interaksi dengan Server TeamTalk)

Parsing Respons & Command Building:

• Metode parseServerLine menggunakan regular expression yang kompleks. Perlu pengujian menyeluruh terhadap berbagai format respons server TeamTalk, terutama untuk versi server yang berbeda atau pembaruan protokol. Pertimbangkan unit test yang lebih komprehensif.
• Fungsi escapeString dan unescapeString krusial untuk keamanan dan integritas perintah. Pastikan semua string yang dikirim/diterima diproses dengan benar.

Manajemen State Internal:

• TeamTalkClient menyimpan state pengguna online ($this->users) dan channel ($this->channels). Sinkronisasi state ini penting. Perhatikan potensi race condition atau inkonsistensi jika instance client di-share antar request konkuren (meskipun saat ini cenderung per-request).
• Setiap request API membuat instance TeamTalkClient baru, yang menyebabkan overhead koneksi dan login berulang ke server TeamTalk. Pertimbangkan strategi caching koneksi atau penggunaan koneksi persisten jika memungkinkan dan aman dalam lingkungan deployment kamu (misalnya dengan Swoole/RoadRunner), namun ini akan menambah kompleksitas terkait manajemen koneksi dan state.

Error Handling & Exception:

• TeamTalkClientException adalah exception generik. Pertimbangkan untuk membuat exception yang lebih spesifik (misalnya, TeamTalkAuthenticationException, TeamTalkResourceNotFoundException, TeamTalkCommandFailedException) untuk penanganan yang lebih baik di level Rute.

Timeout & Operasi Blocking:

• Operasi socket (fgets, fwrite) bersifat blocking. Pastikan timeout (socketTimeout dan timeout internal di processResponsesUntilBlockEnd) dikonfigurasi dengan baik untuk mencegah request API menggantung terlalu lama.

Kelengkapan Fitur (dibandingkan tt5admin.php):

• Banyak fitur administratif dari tt5admin.php belum diimplementasikan di API (misalnya, kick/ban/move user, op/deop, manajemen server properties seperti nama server/MOTD, save config, query stats, dll.). Ini adalah area potensial untuk pengembangan.
• Parameter diskquota untuk channel ada di tt5admin.php dan TeamTalkClient (sebagai parameter yang diizinkan), tetapi belum tervalidasi atau digunakan secara penuh di Rute.

Refactoring Potensial:

• Seiring bertambahnya fitur, kelas TeamTalkClient bisa menjadi sangat besar. Pertimbangkan untuk memecahnya menjadi kelas-kelas yang lebih kecil dengan tanggung jawab spesifik (misalnya, ChannelManager, AccountManager yang menggunakan objek koneksi dasar).

2. Struktur dan Logika Rute (src/Routes/)

• Duplikasi Kode: Terdapat pola koneksi, login, dan error handling dasar yang berulang di setiap metode Rute. Pertimbangkan penggunaan base handler/controller atau trait untuk mengurangi duplikasi.
• Validasi Input: Validasi input sudah ada, tetapi pastikan selalu komprehensif dan aman.
• Sinkronisasi State Client dengan Respons API: Setelah operasi modifikasi (misalnya, PUT /channels/{id}), ada upaya untuk mengambil state terbaru dari TeamTalkClient untuk disertakan dalam respons. Logika ini (termasuk potensi reconnect di ChannelRoutes) mungkin perlu kamu tinjau untuk efisiensi dan keandalan.

3. Konfigurasi (src/settings.php)

• Keamanan Kredensial: SANGAT PENTING untuk tidak menyimpan kredensial (password TeamTalk, API key) secara hardcoded di settings.php untuk lingkungan produksi. Gunakan environment variables server atau sistem manajemen konfigurasi yang aman.

4. Pengujian (Testing)

• Unit Tests: phpunit sudah ada di composer.json. Prioritaskan pembuatan unit test untuk:
  • Logika krusial di TeamTalkClient.php (parsing, command building, state management).
  • Validasi input dan logika bisnis di setiap kelas Rute.
  • Fungsionalitas middleware (ApiKeyAuthMiddleware).
• Integration Tests: Lakukan pengujian API secara menyeluruh dengan server TeamTalk yang aktif untuk memastikan interaksi end-to-end berfungsi dengan benar.

5. Keamanan

• Rate Limiting: Implementasikan mekanisme rate limiting untuk melindungi API dari penyalahgunaan atau serangan brute-force.
• Input Sanitization: Selain validasi, pastikan semua input benar-benar disanitasi sebelum digunakan, terutama jika ada interaksi langsung dengan sistem file atau database di masa depan.
• Ketergantungan: Selalu perbarui ketergantungan (via composer update) untuk mendapatkan patch keamanan terbaru.

6. Performa dan Skalabilitas

• Koneksi Berulang: Seperti disebutkan, koneksi dan login berulang ke TeamTalk per request API bisa menjadi bottleneck. Evaluasi dampaknya dan pertimbangkan solusi jika menjadi masalah.
• Operasi Kompleks: Beberapa operasi seperti getChannelIdByPath atau getChannelPathById bisa menjadi lambat jika struktur channel sangat besar/dalam.

7. Dokumentasi Kode

• Lengkapi dan jaga konsistensi PHPDoc block untuk semua kelas, metode, dan properti untuk memudahkan pemahaman dan pemeliharaan kode oleh tim atau kontributor di masa depan.

8. Manajemen Versi API

• Jika ada perubahan yang signifikan dan berpotensi breaking change pada fungsionalitas atau struktur respons API di masa depan, pertimbangkan untuk memperkenalkan versioning pada path API (misalnya, /api/v2/...).

9. tt5admin.php sebagai Referensi Utama

• Skrip tt5admin.php asli dari BearWare.dk adalah sumber kebenaran untuk format perintah dan interaksi dengan server TeamTalk 5. Selalu rujuk ke skrip ini saat kamu mengimplementasikan fungsionalitas baru atau memecahkan masalah terkait protokol.

Corat-coret