Przewodnik migracji

Migracja z v1 na v2

Ten przewodnik opisuje zmiany, które musisz wprowadzić przy aktualizacji z SteamApis API v1 do v2. v2 dodaje nowe kategorie (Konto, Market Data), reorganizuje endpointy użytkowników Steam i aplikacji oraz wprowadza ustandaryzowaną kopertę odpowiedzi.

Uwierzytelnianie

v1 przekazywało klucz API jako query parameter, zazwyczaj api_key lub key:

GET /steam/profile/76561198038526790?api_key=YOUR_KEY

v2 przekazuje klucz API przez header x-api-key (zalecane) lub query parameter ?key= (nadal wspierany):

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

Zalecamy header, bo klucz nie pojawia się wtedy w logach serwera, historii przeglądarki ani nagłówkach referer.

Koperta odpowiedzi

v1 zwracało dane bezpośrednio na najwyższym poziomie:

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

v2 opakowuje każdą odpowiedź w standardową kopertę. Dokładny kształt zależy od tego, czy endpoint zwraca pojedynczy zasób czy paginowaną listę:

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

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

Błędy używają tej samej koperty z success: false:

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

Aby dostać się do danych, użyj data.result (pojedynczy zasób) lub data.results (lista) zamiast czytać najwyższy poziom bezpośrednio.

Zmiany nazw pól użytkownika Steam

Endpoint użytkownika v2 zwraca te same dane Steam, ale z nazwami pól w camelCase i zagnieżdżonym obiektem avatar. Jeśli parsujesz odpowiedzi użytkownika, zaktualizuj swoje typy:

Parametr Steam ID

W v1 endpointy użytkownika wymagały SteamID64 (17-cyfrowego identyfikatora numerycznego). W v2 parametr steamid akceptuje wiele formatów Steam ID — SteamID64, SteamID, SteamID3 — a API rozwiązuje je automatycznie.

Mapowanie endpointów

Poniższe tabele mapują każdy endpoint v1 na jego odpowiednik w v2, pogrupowane według kategorii. Wpisy oznaczone "Nowe w v2" nie mają poprzednika w v1.

Konto

Użytkownicy Steam

Aplikacje Steam

Przedmioty Steam

Obrazy

Market Data (zewnętrzne marketplace'y)

Market Data to nowa kategoria w v2. Agreguje dane cenowe, oferty, sprzedaże i order book z 26 zewnętrznych marketplace'ów — funkcjonalność, która nie istniała w v1.

Oprócz endpointów REST poniżej v2 udostępnia też strumień ofert WebSocket w czasie rzeczywistym:

Podsumowanie breaking changes

1. Uwierzytelnianie — przenieś klucz API z query parameter api_key na header x-api-key (lub zostaw jako ?key=, jeśli dostęp do headera jest niepraktyczny).
2. Koperta odpowiedzi — rozpakuj data.result (pojedynczy zasób) lub data.results (lista) zamiast czytać najwyższy poziom. Paginowane odpowiedzi list zawierają też cursor i hasMore.
3. Pola użytkownika Steam — zmień nazwy steamid → steamID, personaname → nickname, profileurl → url i innych (patrz pełna tabela wyżej). Płaskie pola avatara przeniesione do zagnieżdżonego obiektu avatar.
4. Ścieżki endpointów — endpointy użytkowników Steam są teraz pod /v2/steam/users/, endpointy aplikacji pod /v2/steam/apps/, endpointy przedmiotów pod /v2/steam/items/.
5. Wejście Steam ID — v2 akceptuje wiele formatów Steam ID, nie tylko SteamID64.
6. Nowe endpointy — Konto, bans, recently-played, achievements, stats, friends, groups, player-counts, global-achievements, news, schema, store rankings, lista przedmiotów i cała kategoria Market Data.
7. Format błędów — błędy zwracają { "success": false, "error": { "name": "...", "message": "...", "meta": ... } } zamiast różnić się per endpoint.