Руководство по миграции

Миграция с v1 на v2

Это руководство описывает изменения, которые тебе нужно внести при переходе с SteamApis API v1 на v2. В v2 добавлены новые категории (Аккаунт, Market Data), реорганизованы endpoint'ы Steam-пользователей и приложений и введена стандартизированная обёртка ответа.

Аутентификация

v1 передавала API-ключ как query-параметр, обычно api_key или key:

GET /steam/profile/76561198038526790?api_key=YOUR_KEY

v2 передаёт API-ключ через request header x-api-key (рекомендуется) или query-параметр ?key= (всё ещё поддерживается):

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

Использовать header рекомендуется, потому что так ключ не попадает в серверные логи, историю браузера и referer'ы.

Обёртка ответа

v1 возвращала данные напрямую на верхнем уровне:

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

v2 оборачивает каждый ответ в стандартную обёртку. Точная форма зависит от того, возвращает ли endpoint одиночный ресурс или постраничный список:

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

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

Ошибки используют ту же обёртку с success: false:

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

Чтобы получить данные, используй data.result (одиночный ресурс) или data.results (список) вместо чтения верхнего уровня напрямую.

Переименования полей Steam-пользователя

v2-endpoint пользователя возвращает те же данные Steam, но с именами полей в camelCase и вложенным объектом avatar. Если ты парсишь ответы по пользователям, обнови свои типы:

Параметр Steam ID

В v1 endpoint'ы пользователей требовали SteamID64 (17-значный числовой ID). В v2 параметр steamid принимает несколько форматов Steam ID — SteamID64, SteamID, SteamID3 — и API разрешает их автоматически.

Маппинг endpoint'ов

Таблицы ниже сопоставляют каждый v1-endpoint с его v2-эквивалентом, сгруппированы по категории. Записи с пометкой «Новое в v2» не имеют v1-предшественника.

Аккаунт

Steam-пользователи

Steam-приложения

Steam-предметы

Изображения

Market Data (сторонние маркетплейсы)

Market Data — новая категория в v2. Агрегирует ценовые данные, офферы, продажи и order book с 26 сторонних маркетплейсов — функциональность, которой не было в v1.

Помимо REST-endpoint'ов ниже, v2 также предоставляет WebSocket-стрим офферов в реальном времени:

Сводка критических изменений

1. Аутентификация — перенеси API-ключ из query-параметра api_key в request header x-api-key (или оставь как ?key=, если работать с header'ом непрактично).
2. Обёртка ответа — распаковывай data.result (одиночный ресурс) или data.results (список) вместо чтения верхнего уровня. Постраничные ответы списков также включают cursor и hasMore.
3. Поля Steam-пользователя — переименуй steamid → steamID, personaname → nickname, profileurl → url и далее (см. полную таблицу выше). Плоские поля аватара перенесены во вложенный объект avatar.
4. Пути endpoint'ов — endpoint'ы Steam-пользователей теперь под /v2/steam/users/, endpoint'ы приложений — под /v2/steam/apps/, endpoint'ы предметов — под /v2/steam/items/.
5. Ввод Steam ID — v2 принимает несколько форматов Steam ID, не только SteamID64.
6. Новые endpoint'ы — Аккаунт, bans, recently-played, achievements, stats, friends, groups, player-counts, global-achievements, news, schema, store rankings, список предметов и вся категория Market Data.
7. Формат ошибок — ошибки возвращают { "success": false, "error": { "name": "...", "message": "...", "meta": ... } } вместо разных форматов под разные endpoint'ы.