Geçiş Rehberi

v1'den v2'ye geçiş

Bu rehber, SteamApis API v1'den v2'ye yükseltirken yapman gereken değişiklikleri kapsar. v2 yeni kategoriler ekler (Hesap, Market Data), Steam kullanıcı ve uygulama endpoint'lerini yeniden düzenler ve standart bir yanıt envelope'u tanıtır.

Kimlik Doğrulama

v1, API key'i genellikle api_key veya key adıyla query parameter olarak gönderirdi:

GET /steam/profile/76561198038526790?api_key=YOUR_KEY

v2, API key'i x-api-key request header'ı (önerilir) ya da ?key= query parameter'ı (hâlâ desteklenir) ile gönderir:

fetch('https://api.steamapis.com/v2/steam/users/76561198038526790', {
  headers: { 'x-api-key': 'YOUR_KEY' }
})

Header'ı kullanmanı öneririz çünkü key; sunucu logları, tarayıcı geçmişi veya referer header'larında görünmez.

Yanıt envelope'u

v1 endpoint'leri veriyi en üst seviyede doğrudan döndürürdü:

{
  "steamid": "76561198038526790",
  "personaname": "PEPZ"
}

v2 her yanıtı standart bir envelope içinde sarar. Kesin şekil, endpoint'in tek bir kaynak mı yoksa sayfalı bir liste mi döndürdüğüne bağlıdır:

{
  "success": true,
  "result": { "steamID": "76561198038526790", "nickname": "PEPZ" }
}

{
  "success": true,
  "results": [ { /* ... */ } ],
  "cursor": "6789abcdef012345",
  "hasMore": true
}

Hatalar aynı envelope'u success: false ile kullanır:

{
  "success": false,
  "error": { "name": "NOT_FOUND", "message": "User not found", "meta": {} }
}

Veriye erişmek için en üst seviyeyi doğrudan okumak yerine data.result (tek kaynak) veya data.results (liste) kullan.

Steam kullanıcı alan yeniden adlandırmaları

v2 kullanıcı endpoint'i aynı Steam verisini döndürür, ancak camelCase alan adları ve iç içe avatar objesiyle. Kullanıcı yanıtlarını parse ediyorsan tiplerini güncelle:

Steam ID parametresi

v1'de kullanıcı endpoint'leri SteamID64 (17 haneli sayısal ID) gerektirirdi. v2'de steamid parametresi birden fazla Steam ID formatını kabul eder — SteamID64, SteamID, SteamID3 — ve API bunları otomatik olarak çözer.

Endpoint eşleme

Aşağıdaki tablolar her v1 endpoint'ini kategorilere göre gruplanmış v2 karşılığına eşler. "v2'de yeni" olarak işaretli girişlerin v1 öncülü yoktur.

Hesap

Steam kullanıcıları

Steam uygulamaları

Steam item'ları

Görseller

Market Data (üçüncü taraf marketplace'ler)

Market Data, v2'de yeni bir kategoridir. 26 üçüncü taraf marketplace'ten fiyat, teklif, satış ve order book verilerini toplar — v1'de var olmayan bir işlevsellik.

Aşağıdaki REST endpoint'lerine ek olarak v2, gerçek zamanlı bir WebSocket teklif akışı da sunar:

Breaking changes özeti

1. Kimlik doğrulama — API key'i api_key query parameter'ından x-api-key request header'ına taşı (veya header erişimi pratik değilse ?key= olarak bırak).
2. Yanıt envelope'u — en üst seviyeyi doğrudan okumak yerine data.result (tek kaynak) veya data.results (liste) olarak aç. Sayfalı liste yanıtları ayrıca cursor ve hasMore içerir.
3. Steam kullanıcı alanları — steamid → steamID, personaname → nickname, profileurl → url ve diğerlerini yeniden adlandır (yukarıdaki tam tabloya bak). Düz avatar alanları iç içe bir avatar objesine taşındı.
4. Endpoint yolları — Steam kullanıcı endpoint'leri artık /v2/steam/users/ altında, uygulama endpoint'leri /v2/steam/apps/ altında, item endpoint'leri /v2/steam/items/ altında. |
5. Steam ID girişi — v2 yalnızca SteamID64 değil, birden fazla Steam ID formatını kabul eder.
6. Yeni endpoint'ler — Hesap, bans, recently-played, achievements, stats, friends, groups, player-counts, global-achievements, news, schema, store rankings, item listesi ve Market Data kategorisinin tamamı.
7. Hata formatı — hatalar, endpoint bazında değişmek yerine { "success": false, "error": { "name": "...", "message": "...", "meta": ... } } döndürür.