API Dokümantasyonu

Başlarken

Her sunucu listelemesinin kendine ait bir API anahtarı vardır. Anahtarı Sunucularım sayfasında ilgili sunucunun satırındaki API anahtarı düğmesinden üretirsin. Anahtar yalnızca üretildiği anda bir kez gösterilir; kaybedersen aynı panelden yeni bir anahtar üretebilirsin.

• Anahtar oluştur: Sunucu için ilk anahtarı üretir.
• Yeni anahtar üret (roll): Yeni bir anahtar verir ve eski anahtarı anında geçersiz kılar. Eklentindeki değeri hemen güncelle.
• Erişimi kapat: Anahtarı silmeden API erişimini durdurur; istekler 403 döner. İstediğin zaman tekrar açabilirsin.

Anahtarını herkese açık yerlerde (GitHub, Pastebin, istemci tarafı JavaScript) paylaşma. Sızdığından şüphelenirsen anahtarı yenile.

Anahtar yönetimi de sınırlıdır: sunucu başına saatte en fazla 5 kez yeni anahtar üretebilir, 8 kez API erişimini açıp kapatabilirsin.

Temel adres ve kimlik doğrulama

https://mcadres.com/api/v1

Anahtarı iki yoldan gönderebilirsin. Sorgu parametresi klasik oy eklentileriyle uyum için, başlık ise sunucu tarafı entegrasyonlar için önerilir.

?key=mca_live_XXXXXXXXXXXXXXXXXXXXXXXX

Authorization: Bearer mca_live_XXXXXXXXXXXXXXXXXXXXXXXX

Hız limitleri ve önbellek

• Okuma uç noktaları: anahtar başına dakikada 120 istek.
• Claim yazma (POST): anahtar başına dakikada 60 istek.
• Geçersiz anahtarla yapılan istekler: IP başına dakikada 30 istek.
• Liste ve detay uç noktalarının çıktısı 3 dakika önbelleklenir. Claim uç noktaları önbelleklenmez, her zaman anlık veriyi döner.

Her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. Limit aşılırsa 429 ile birlikte Retry-After başlığı döner. Önbellekten dönen yanıtlarda verinin kaç saniyelik olduğunu X-Cache-Age başlığından okuyabilirsin.

Bir kullanıcının oy verip vermediğini kontrol etme

Kullanıcının son 24 saat içinde oy verip vermediğini ve oyun ödülünün alınıp alınmadığını kontrol eder. Ödül eklentileri için tasarlanmıştır; yalnızca son 24 saate bakar.

Varsayılan yanıt gövdesi yalnızca bu sayıdır (text/plain), böylece eklentiler doğrudan ayrıştırabilir.

Bir kullanıcının oyunu ödüllendirildi olarak işaretleme

Kullanıcının son 24 saatteki en yeni ödülsüz oyunu alındı olarak işaretler. Ödül verildikten sonra çağır ki aynı oy iki kez ödüllendirilmesin.

Oy veren listesi

Sunucuna oy verenleri toplam oy sayısına göre sıralı döner. En fazla 500 sonuç verilir ve çıktı 3 dakika önbelleklenir.

[
  { "nickname": "Steve", "votes": 24, "lastVoteAt": "2026-08-04T09:12:41.000Z" },
  { "nickname": "Alex",  "votes": 19, "lastVoteAt": "2026-08-04T07:55:02.000Z" }
]

Oy listesi

Sunucuna gelen son oyları tek tek döner. En fazla son 500 kayıt verilir ve çıktı 3 dakika önbelleklenir.

[
  {
    "nickname": "Steve",
    "timestamp": 1785835961,
    "votedAt": "2026-08-04T09:12:41.000Z",
    "claimed": true
  }
]

timestamp saniye cinsinden Unix zamanıdır. claimed alanı oyun ödülünün alınıp alınmadığını gösterir.

Sunucu detayı

Sunucunun tüm listeleme bilgilerini JSON olarak döner. Kendi durum sayfanı oluşturmak için kullanabilirsin. Çıktı 3 dakika önbelleklenir.

{
  "slug": "ornek-sunucu",
  "name": "Örnek Sunucu",
  "url": "https://mcadres.com/sunucu/ornek-sunucu",
  "address": "oyna.ornek.com",
  "hostname": "oyna.ornek.com",
  "port": 25565,
  "platform": "Java Edition",
  "gameModes": ["Survival", "SkyBlock"],
  "version": "1.21.x",
  "versionMin": "1.8",
  "versionMax": "1.21.4",
  "shortDescription": "Türkiye'nin en iyi survival sunucusu.",
  "status": "active",
  "online": true,
  "players": { "online": 128, "max": 500 },
  "lastPingAt": "2026-08-04T09:14:00.000Z",
  "thumbnailUrl": "https://mcadres.com/api/media/...",
  "bannerUrl": null,
  "discordUrl": "https://discord.gg/...",
  "websiteUrl": null,
  "storeUrl": null,
  "createdAt": "2026-01-14T18:02:11.000Z",
  "votifier": { "enabled": true, "protocol": "v2" },
  "votes": { "total": 8421, "month": 512, "previousMonth": 934, "today": 37 }
}

Hata yanıtları

Hatalar HTTP durum kodu ile birlikte { "error": "...", "code": "..." } gövdesi döner.

Örnekler

# Oy kontrolü
curl "https://mcadres.com/api/v1?object=votes&element=claim&key=$KEY&username=Steve"

# Ödülü işaretle
curl -X POST "https://mcadres.com/api/v1?action=post&object=votes&element=claim&key=$KEY&username=Steve"

# Bu ayın oy verenleri (ilk 50)
curl -H "Authorization: Bearer $KEY" \
  "https://mcadres.com/api/v1?object=servers&element=voters&month=current&format=json&limit=50"

# Sunucu detayı
curl -H "Authorization: Bearer $KEY" \
  "https://mcadres.com/api/v1?object=servers&element=detail"