Документация Steamworks
Обзор веб-API

Введение

В Steam встроен основанный на HTTP веб-API, который может использоваться для доступа ко многим функциям Steamworks. Этот API содержит публичные методы, доступ к которым может получить любое приложение, способное отправить HTTP-запрос, к примеру игровой клиент или сервер. Он также содержит защищённые методы, которые требуют аутентификации, к ним доступ могут получить доверенные серверные приложения.

У примеру, методы веб-API обычно используются защищённым сервером издателя в следующих целях:
  • Верификация данных учетной записи пользователя Steam на сервере
  • Проверка владения приложением
  • Сохранение или получение данных о статистиках, достижениях и счёта пользователей в списках лидеров
  • Проведение внутриигровых покупок

Полный список доступных функций веб-API Steamworks доступен здесь.

Формат запроса

Запросы к публичным функциям веб-API Steamworks отправляются как HTTP (порт 80) или HTTPS (порт 443) запросы к api.steampowered.com.
Издатели также могут отправлять запросы к работающему только для партнёров серверу веб-API здесь: https://partner.steam-api.com. Этот сервер более доступен, чем публичный, так что вы должны использовать его для всех запросов со своих защищённых серверов. Дополнительная информация здесь: Соображения об адресах узлов веб-API и брандмауэрах.

Как и API Steamworks на С++, веб-API разделён на множество интерфейсов, содержащих связанные методы. Формат URI для запроса к API таков:
https://api.steampowered.com/<interface>/<method>/v<version>/

Большинство методов поддерживают несколько обязательных и необязательных параметров. В зависимости от метода, эти параметры необходимо отправлять, используя GET или POST.

Все запросы необходимо отправлять по протоколу HTTP 1.1 с SSL версии 3.0 и 128-битным шифрованием, если возможно. Content-Type должен быть указан как application/x-www-form-urlencoded, а параметры POST должны содержаться в теле запроса в стандартном формате URL-кодирования. Текст должен быть в UTF-8.

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

Доступ ко многим методы веб-API ограничен, для их использования потребуется уникальный ключ. См. Авторизация с помощью ключей веб-API

Параметры массива

Для некоторых методов необходим массив параметров. На это указывает постфикс [0] в названии параметра. При передаче массива указывается параметр count, который уточняет число параметров в массиве. Пример:
?count=2&name[0]=SomeNameHere&name[1]=SomeOtherName

Служебные интерфейсы

В дополнение к обычным вызовам веб-API существуют служебные интерфейсы. Они подобны обычным интерфейсам с тем исключением, что все служебные функции помимо параметров GET и POST могут принимать один объект в формате JSON. Чтобы передать данные в JSON, вызовите метод веб-API с параметром input_json в следующем формате:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

Обратите внимание, что JSON должен быть закодирован в виде URL. Поля key и format по-прежнему передаются как отдельные параметры. Запросы POST также поддерживаются.

Определить, является ли метод служебным, можно по названию: если в окончании названия есть "Service", к примеру IPlayerService, это означает, что он поддерживает дополнительный метод передачи параметров. Параметры некоторых служебных методов имеют более сложную структуру и требуют альтернативный формат ввода.

Пример запроса

В следующем примере запрос возвращает 3 последние новости о Team Fortress 2.
Запрос уточняет, что ответ должен быть в формате JSON, и включает в себя обязательный параметр appid (AppID Team Fortress 2 равен 440) и необязательный параметр — число возвращаемых результатов.

GET /ISteamNews/GetNewsForApp/v2/?appid=440&count=3\r\n Host: api.steampowered.com/r/n Content-Length: 0\r\n\r\n

Вы можете выполнить запрос и получить результаты по этой ссылке:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

Дополнительная информация об этом вызове доступна здесь: ISteamNews/GetNewsForApp

Получение Steam ID пользователя

веб-API Steamworks идентифицирует отдельных пользователей с помощью их уникальных 64-битных Steam ID. Получение SteamID пользователя описано в разделе Аутентификация и проверка владения.

Соображения об адресах узлов веб-API и брандмауэрах

Публичный веб-API (api.steampowered.com) находится за пограничным сервером кэширования Akamai, так что IP-адреса, которые вы увидите, будут разниться в зависимости от того, где вы находитесь, а также от других факторов. IP-адреса могут часто меняться, так что если вы выполняете запросы из-за брандмауэра, ограничивающего исходящие запросы, продолжайте читать.

Для запросов с ваших защищённых серверов необходимо указывать узел https://partner.steam-api.com, который используется только партнёрами. У этого узла есть отличные от общедоступного узла свойства:
  • Доступ к этом узлу возможен только по HTTPS.
  • Этот узел не находится за пограничным сервером кэширования Akamai.
  • Каждый запрос к этому узлу должен выполняться с использованием издательского ключа, даже если запрос, не требующий ключа. Запросы без ключа вернут ошибку 403.
  • Requests generating 403 status codes, which typically happens when using a regular Web API key instead of your publisher key, will incur strict rate limits for the connecting IP. Это сделано для того, чтобы убедиться в высокой доступности узла.
  • Если вы отправляете запросы с узла, имеющего фильтр брандмауэра на исходящие запросы, вы должны добавить DNS 'partner.steam-api.com' в разрешённый список. Если ваш брандмауэр принимает только цифровые адреса, добавьте следующий бесклассовый адрес в разрешённый список: 208.64.200.0/22.
    Обратите внимание: не подключайтесь к серверам веб-API по IP, используйте DNS-имя. Данный адрес предоставляется только для клиентов, которым нужно добавить его в разрешённый список в брандмауэре.

IP Address Whitelisting

We allow whitelisting of IP addresses for WebAPI calls. This is an added layer of security in the event that your WebAPI key is compromised, because it ensures that only WebAPI calls from whitelisted IP addresses will be successful. Once any IP is set to be whitelisted, all other requests from non-whitelisted addresses will be blocked and return a 403 - Forbidden response.

Adding IP addresses to the whitelist is easy. From any Group page that has a WebAPI key, click the "Manage WebAPI Key" button and follow the instructions.

Each WebAPI key has its own whitelist, and adding ip addresses to the whitelist is not required.

Note: Whitelisting does not guarantee WebAPI key security. Protect your key, do not share it, and change it immediately if it is compromised.