# GmodTR Geliştirici API'si

gmod.tr'deki Türk Garry's Mod sunucularının herkese açık bilgilerini (oyuncu sayısı, harita,
mod, uptime, skor, sıra, aylık oy) okumak ve sunucu sahipleri için oy karşılığı oyun içi ödül
vermek için API. Ücretsiz; her istek bir API anahtarıyla yapılır.

- Temel adres: `https://gmod.tr/api/v1`
- OpenAPI şeması: https://gmod.tr/api/v1/openapi.json
- API kataloğu (RFC 9727): https://gmod.tr/.well-known/api-catalog
- Kimlik doğrulama rehberi (ajanlar için): https://gmod.tr/auth.md
- İnsanlar için sayfa: https://gmod.tr/devs

## Anahtar türleri

| Tür | Önek | Kim alır | Neye erişir |
|---|---|---|---|
| Kişisel anahtar | `gmtd_` | Steam ile giriş yapan herkes, profilinden: https://gmod.tr/sunucularim → API anahtarlarım (hesap başına bir tane) | Herkese açık sunucu bilgileri: `GET /servers`, `GET /servers/{slug}` |
| Sunucu anahtarı | `gmtr_` | Sunucunun sahipliği doğrulanmış sahibi, sunucunun düzenleme sayfasından | Yukarıdakiler + kendi sunucusu ve oy ödülü: `GET /server`, `GET /votes/{steamid}`, `POST /votes/{steamid}/claim` |

Anahtar oluşturmak Kullanım Koşulları'nın "Geliştirici API'si" maddesinin kabulünü gerektirir.
Anahtar sadece oluşturulduğu anda bir kez gösterilir.

## Kimlik doğrulama

Her istekte:

```
Authorization: Bearer <anahtar>
```

Bütün istekler HTTPS. Cevaplar JSON; zamanlar ISO 8601, UTC. JSON alan adları İngilizce ve
kalıcıdır; hata mesajları Türkçedir.

## Uç noktalar

### GET /servers

Listelenen sunucular, skora göre sıralı. Parametreler: `gamemode` (ör. `DarkRP`), `online`
(`true`/`false`), `page` (1'den), `per_page` (1-100, varsayılan 50).

```
curl -H "Authorization: Bearer $GMODTR_KEY" "https://gmod.tr/api/v1/servers?gamemode=DarkRP&online=true"
```

Cevap: `{"items": [Server, ...], "total": 57, "page": 1, "per_page": 50}`

### GET /servers/{slug}

Tek sunucu. Bulunamazsa ya da listeden kaldırılmışsa `404`.

### Server nesnesi

```json
{
  "id": 42,
  "slug": "sunucum",
  "name": "[TR] Sunucum | DarkRP",
  "url": "https://gmod.tr/sunucu/sunucum",
  "vote_url": "https://gmod.tr/oy/sunucum",
  "connect": "185.1.1.1:27015",
  "gamemode": "DarkRP",
  "map": "rp_downtown_v4c",
  "online": true,
  "players": 37,
  "max_players": 64,
  "score": 71.4,
  "rank": 3,
  "votes_month": 412,
  "uptime_7d": 0.9931,
  "verified": true,
  "champion": false,
  "last_queried_at": "2026-09-26T15:30:00Z"
}
```

- `rank`: listelenen bütün sunucular arasında skora göre sıra.
- `score`: 0-100; son 7 günün ortalama oyuncu sayısı (40), ayın oyları (45), 7 günlük uptime (15).
- `votes_month`: bu ayki oylar, her ayın 1'inde sıfırlanır.
- `uptime_7d`: son 7 günde açık kalma oranı (0-1).
- Oyuncu sayıları 15 dakikada bir güncellenir.

### GET /server (sadece sunucu anahtarı)

Anahtarın ait olduğu sunucu (Server nesnesi).

### GET /votes/{steamid} (sadece sunucu anahtarı)

Bu Steam hesabı (SteamID64) son 24 saatte sunucuya oy verdi mi, ödülünü aldı mı?

```json
{
  "steamid": "76561198000000000",
  "voted": true,
  "voted_at": "2026-09-26T10:12:45Z",
  "claimed": false,
  "claimed_at": null,
  "vote_reset_at": "2026-09-27T09:00:00Z"
}
```

### POST /votes/{steamid}/claim (sadece sunucu anahtarı)

Ödülü "verildi" olarak işaretler; her oy için yalnızca bir kez başarılı olur (aynı anda iki
istek gelse bile). Ödülü vermeden önce çağır, sadece `200` gelince ver. `404`: son 24 saatte
oy yok. `409`: ödül zaten alınmış.

## Oy kuralları

- Her Steam hesabı bütün site genelinde günde yalnızca bir sunucuya oy verebilir.
- Oy hakkı her gün İstanbul saatiyle 12:00'de (09:00 UTC) yenilenir.
- Bir oy verildikten sonraki 24 saat içinde ödüle çevrilebilir; her oyun ödülü bir kez alınır.

## Hatalar ve sınırlar

Hatalar `{"detail": "..."}` gövdesiyle döner.

| Kod | Anlamı |
|---|---|
| 401 | Anahtar yok ya da geçersiz |
| 403 | Anahtar artık geçerli değil (sunucu sahipliği değişti ya da sunucu kaldırıldı), kişisel anahtarla sunucu anahtarı gerektiren uç çağrıldı ya da istek başka bir siteden tarayıcıyla gönderildi |
| 404 | Sunucu ya da ödülü alınacak oy yok |
| 409 | Ödül zaten alınmış |
| 422 | Geçersiz parametre (ör. steamid bir SteamID64 değil) |
| 429 | Hız sınırı; `Retry-After` başlığındaki saniye kadar bekle |

Sınır: anahtar başına dakikada 120 istek.

## Sürümleme

`/api/v1` kararlıdır. Yeni alanlar ve uçlar eklenebilir; tanımadığın alanları yok say. Bir alanın
adının değişmesi ya da kaldırılması sadece `/api/v2` ile ve önceden duyurularak olur.

## Koşullar ve gizlilik

- API'den kişisel veri olarak sadece, sunucu sahibinin sorguladığı Steam hesabının kendi
  sunucusuna son 24 saatteki oyu ve ödül durumu çıkar. Oyuncu adları, oy verenlerin listesi ve IP
  adresleri API'de yoktur.
- Oy bilgisi sadece oyun içi ödül vermek için kullanılabilir; yayımlanamaz, paylaşılamaz.
- Verileri herkese açık gösteren uygulamalar kaynak olarak gmod.tr'yi belirtip bağlantı verir.
- Oy satın almak, bot ya da çoklu hesapla oy vermek yasaktır.
- Bağlayıcı metinler: https://gmod.tr/yasal/kosullar (6. madde) ve https://gmod.tr/yasal/kvkk