API Dokümantasyonu
İRCPanel REST API kullanım kılavuzu ve referans dokümantasyonu
Giriş
İRCPanel API, IRC botlarınızdan log kaydetmenizi, istatistikleri sorgulamanızı ve verileri yönetmenizi sağlar. API, REST mimarisi kullanır ve JSON formatında veri döndürür.
https://ircpanel.com/api/
Her API key sadece kendi verilerine erişebilir. Tüm endpoint'ler otomatik olarak kullanıcı bazlı filtreleme yapar.
Özellikler
- RESTful API mimarisi
- JSON formatında veri alışverişi
- API Key bazlı kimlik doğrulama
- Kullanıcı bazlı veri izolasyonu
- Rate limiting koruması
- Detaylı hata mesajları
Kimlik Doğrulama
Tüm API istekleri için geçerli bir API anahtarı gereklidir. API anahtarınızı HTTP Header olarak göndermelisiniz.
API Key Kullanımı
X-API-Key: ircsp_your_api_key_here
API anahtarınızı asla herkese açık kodlarda veya client-side JavaScript'te kullanmayın. Anahtarınızı güvenli bir yerde saklayın.
API Key Oluşturma
Yeni bir API anahtarı oluşturmak için:
- Giriş yapın
- API Keys sayfasına gidin
- "Yeni API Key Oluştur" butonuna tıklayın
- Anahtarınızı kopyalayın ve güvenli bir yerde saklayın
Hata Kodları
API, standart HTTP durum kodları kullanır:
| Kod | Açıklama |
|---|---|
200 |
İşlem başarılı |
400 |
Geçersiz istek (eksik veya hatalı parametreler) |
401 |
Kimlik doğrulama hatası (geçersiz API key) |
403 |
Erişim reddedildi (yetkisiz işlem) |
404 |
Kaynak bulunamadı |
429 |
Çok fazla istek (rate limit aşıldı) |
500 |
Sunucu hatası |
Hata Response Örneği
{
"success": false,
"error": "Invalid API key",
"code": 401
}
Log Kaydetme
IRC kanallarınızdan log kaydetmek için bu endpoint'i kullanın. Loglar otomatik olarak API key sahibine ait sunucu altında kaydedilir.
Bu endpoint SADECE IRC BOTLARI (TCL/Eggdrop) için tasarlanmıştır! Web sitenizden bu endpoint'e istek atmayın, yoksa web sunucu IP'niz bot olarak kaydedilir. Web sitenizde sadece
/api/stats, /api/logs ve /api/servers kullanın.
Bot IP'niz otomatik olarak algılanır ve sunucu kaydı yoksa oluşturulur. Manuel sunucu eklemenize gerek yoktur.
Endpoint
POST /api/log
Parametreler
| Parametre | Tip | Zorunluluk | Açıklama |
|---|---|---|---|
type |
string | Zorunlu | Log tipi: PRIVMSG, JOIN, PART, QUIT, KICK, MODE, NICK, TOPIC, HEARTBEAT |
nick |
string | Zorunlu | Kullanıcı nickname |
channel |
string | Zorunlu | Kanal adı (# ile başlamalı) |
message |
string | Opsiyonel | Mesaj içeriği |
timestamp |
integer | Opsiyonel | Unix timestamp (varsayılan: şimdiki zaman) |
Örnek İstek
curl -X POST https://ircpanel.com/api/log \
-H "X-API-Key: ircsp_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"type": "PRIVMSG",
"nick": "kullanici",
"channel": "#genel",
"message": "Merhaba dünya!",
"timestamp": 1697000000
}'
Başarılı Response
{
"success": true,
"message": "Log saved successfully",
"log_id": 12345
}
İstatistikler
Kanal ve kullanıcı istatistiklerini sorgulayın. Bu endpoint sadece sizin API key'inize ait verileri döndürür.
Bu endpoint otomatik olarak sadece sizin loglarınızı filtreler. Başka kullanıcıların verilerini göremezsiniz.
Endpoint
GET /api/stats
Parametreler
Bu endpoint parametre almaz. Tüm istatistiklerinizi döndürür.
Örnek İstek
curl -X GET "https://ircpanel.com/api/stats" \ -H "X-API-Key: ircsp_your_api_key_here"
Response
{
"success": true,
"stats": {
"total_messages": 1542,
"total_users": 45,
"active_channels": 3,
"most_active_user": "kullanici1",
"most_active_channel": "#genel"
}
}
Log Arama ve Listeleme
Kayıtlı loglarınızı arayın ve filtreleyin. Bu endpoint sadece sizin API key'inize ait logları döndürür.
Kanal, kullanıcı veya log tipine göre filtreleyebilirsiniz. Tüm filtreler otomatik olarak sizin verilerinizle sınırlıdır.
Endpoint
GET /api/logs
Parametreler
| Parametre | Tip | Zorunluluk | Açıklama |
|---|---|---|---|
channel |
string | Opsiyonel | Kanal filtresi (örn: #genel) |
nick |
string | Opsiyonel | Kullanıcı nickname filtresi |
type |
string | Opsiyonel | Log tipi filtresi (PRIVMSG, JOIN, PART, vb.) |
limit |
integer | Opsiyonel | Sonuç limiti (varsayılan: 20, max: 100) |
offset |
integer | Opsiyonel | Sayfalama için offset değeri (varsayılan: 0) |
Örnek İstek
curl -X GET "https://ircpanel.com/api/logs?channel=#genel&limit=50" \ -H "X-API-Key: ircsp_your_api_key_here"
Response
{
"success": true,
"total": 150,
"limit": 50,
"offset": 0,
"logs": [
{
"id": 12345,
"type": "PRIVMSG",
"nick": "kullanici1",
"channel": "#genel",
"message": "Merhaba!",
"timestamp": 1697000000,
"created_at": "2024-10-11 12:00:00"
}
]
}
Sunucu Listesi
API key'inize bağlı tüm IRC sunucularını listeleyin.
Sunucular ilk log gönderildiğinde otomatik olarak oluşturulur. Manuel ekleme gerekmez.
Endpoint
GET /api/servers
Parametreler
Bu endpoint parametre almaz.
Örnek İstek
curl -X GET "https://ircpanel.com/api/servers" \ -H "X-API-Key: ircsp_your_api_key_here"
Response
{
"success": true,
"servers": [
{
"id": 1,
"user_id": 123,
"server_name": "Server-192.168.1.100",
"bot_ip": "192.168.1.100",
"status": "active",
"last_seen": "2024-11-07 12:00:00",
"created_at": "2024-11-01 10:00:00"
}
]
}
PHP Örneği (Web Sitesi İçin)
PHP ile API kullanım örneği. Bu kodu kendi web sitenizde kullanarak istatistiklerinizi gösterebilirsiniz.
API key'iniz otomatik olarak sadece sizin verilerinize erişim sağlar. Başka kullanıcıların verilerini göremezsiniz.
Web sitenizde
/api/log kullanmayın! Bu endpoint sadece IRC botları içindir.
Aşağıdaki örnekler web sitesi için güvenlidir.
İstatistik Çekme Örneği
<?php
$apiKey = 'ircsp_your_api_key_here';
$apiUrl = 'https://ircpanel.com/api/stats';
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Key: ' . $apiKey
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode == 200) {
$result = json_decode($response, true);
// İstatistikleri göster
echo "<h2>İRC İstatistiklerim</h2>";
echo "<p>Toplam Log: " . $result['stats']['total_logs'] . "</p>";
echo "<p>Bugünkü Log: " . $result['stats']['today_logs'] . "</p>";
echo "<p>Aktif Sunucu: " . $result['stats']['active_servers'] . "</p>";
if ($result['stats']['top_channel']) {
echo "<p>En Aktif Kanal: " . $result['stats']['top_channel']['channel'];
echo " (" . $result['stats']['top_channel']['count'] . " mesaj)</p>";
}
} else {
echo "Hata: İstatistikler alınamadı";
}
?>
Log Listeleme Örneği
<?php
$apiKey = 'ircsp_your_api_key_here';
$apiUrl = 'https://ircpanel.com/api/logs?limit=10&channel=#genel';
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Key: ' . $apiKey
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode == 200) {
$result = json_decode($response, true);
echo "<h2>Son Loglar (#genel)</h2>";
echo "<p>Toplam: " . $result['total'] . " log</p>";
foreach ($result['logs'] as $log) {
echo "<div>";
echo "<strong>" . htmlspecialchars($log['nick']) . "</strong>: ";
echo htmlspecialchars($log['message'] ?? $log['type']);
echo " <small>(" . $log['created_at'] . ")</small>";
echo "</div>";
}
} else {
echo "Hata: Loglar alınamadı";
}
?>
cURL Örneği
Komut satırından API kullanımı (test ve debug için):
/api/log endpoint'ini manuel olarak test etmeyin!
Sadece IRC botunuzdan (TCL script) kullanın. Aksi halde sunucu IP'niz bot olarak kaydedilir.
İstatistik Sorgulama
curl -X GET "https://ircpanel.com/api/stats?channel=#genel" \ -H "X-API-Key: ircsp_your_api_key_here"
Eggdrop TCL Örneği
Eggdrop bot için TCL scripti örneği:
# İRCPanel - Eggdrop TCL Script
# Version: 1.0
# API Ayarları
set ircstats_api_key "ircsp_your_api_key_here"
set ircstats_api_url "https://ircpanel.com/api/log"
# Paketler
package require http
package require json
# Log gönderme fonksiyonu
proc send_to_ircstats {type nick channel {message ""}} {
global ircstats_api_key ircstats_api_url
set data [list \
type $type \
nick $nick \
channel $channel \
message $message \
timestamp [clock seconds]
]
set json_data [::json::write object {*}$data]
set token [http::geturl $ircstats_api_url \
-method POST \
-headers [list \
X-API-Key $ircstats_api_key \
Content-Type "application/json" \
] \
-query $json_data
]
set status [http::status $token]
http::cleanup $token
return $status
}
# Mesaj yakalama
bind pubm - * ircstats_pubm
proc ircstats_pubm {nick host hand chan text} {
send_to_ircstats "PRIVMSG" $nick $chan $text
return 0
}
# Join yakalama
bind join - * ircstats_join
proc ircstats_join {nick host hand chan} {
send_to_ircstats "JOIN" $nick $chan ""
return 0
}
# Part yakalama
bind part - * ircstats_part
proc ircstats_part {nick host hand chan msg} {
send_to_ircstats "PART" $nick $chan $msg
return 0
}
# Quit yakalama
bind sign - * ircstats_quit
proc ircstats_quit {nick host hand chan msg} {
send_to_ircstats "QUIT" $nick $chan $msg
return 0
}
# Kick yakalama
bind kick - * ircstats_kick
proc ircstats_kick {nick host hand chan target reason} {
send_to_ircstats "KICK" $target $chan "$nick kicked: $reason"
return 0
}
# Mode yakalama
bind mode - * ircstats_mode
proc ircstats_mode {nick host hand chan mode target} {
send_to_ircstats "MODE" $nick $chan "$mode $target"
return 0
}
# Nick değişikliği
bind nick - * ircstats_nick
proc ircstats_nick {nick host hand chan newnick} {
send_to_ircstats "NICK" $nick $chan "changed nick to $newnick"
return 0
}
# Topic değişikliği
bind topc - * ircstats_topic
proc ircstats_topic {nick host hand chan topic} {
send_to_ircstats "TOPIC" $nick $chan $topic
return 0
}
# Heartbeat (Her 5 dakikada bir)
bind time - "*/5 * * * *" ircstats_heartbeat
proc ircstats_heartbeat {min hour day month year} {
foreach chan [channels] {
send_to_ircstats "HEARTBEAT" "SISTEM" $chan "Bot aktif"
}
return 0
}
putlog "İRCPanel TCL Script yüklendi!"
TCL scriptini kullanmak için
tcllib paketinin yüklü olması gerekir.
Eggdrop bot dizininizde scripts/ircstats.tcl olarak kaydedin ve
eggdrop.conf dosyanıza source scripts/ircstats.tcl satırını ekleyin.
Rate Limiting
API istekleriniz rate limiting kurallarına tabidir:
| Endpoint | Limit | Süre |
|---|---|---|
/api/log |
1000 istek | Saat başı |
/api/stats |
100 istek | Saat başı |
/api/logs |
200 istek | Saat başı |
/api/servers |
100 istek | Saat başı |
Rate limit aşılması durumunda
429 Too Many Requests hatası alırsınız.
Response header'larında kalan istek sayısını görebilirsiniz.
Rate Limit Headers
X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1697000000
En İyi Uygulamalar
1. API Key Güvenliği
- API key'lerinizi asla public repository'lerde paylaşmayın
- Environment variables kullanarak key'leri saklayın
- Kullanılmayan API key'leri devre dışı bırakın
- Her bot için ayrı API key kullanın
2. Performans Optimizasyonu
- Batch işlemler için API'yi gruplu kullanın
- Gereksiz yere sık sorgulama yapmayın
- Heartbeat mesajlarını 5 dakikada bir gönderin
- Cache mekanizmaları kullanın
3. Hata Yönetimi
- Her zaman HTTP status kodlarını kontrol edin
- Retry mekanizması uygulayın (exponential backoff)
- Timeout değerlerini uygun ayarlayın
- Hata loglarını kaydedin
Production ortamında kullanmadan önce test ortamında API'yi test edin.
Destek
API kullanımı hakkında sorularınız mı var?