Общая информация

В 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 Steamworks на С++, веб-API разделён на множество интерфейсов, содержащих связанные методы. Формат URI для запроса к API таков:
Большинство методов поддерживают несколько обязательных и необязательных параметров. В зависимости от метода эти параметры необходимо отправлять в запросе как параметр GET или POST.

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

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

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

Массивы параметров

Для некоторых методов необходим массив параметров. На это указывает постфикс [0] в названии параметра. При передаче массива указывается параметр count, который задаёт число параметров в массиве. Пример:

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

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

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

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

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

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


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

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

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

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

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

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

Для запросов с ваших защищённых серверов необходимо указывать узел https://partner.steam-api.com, который используется только партнёрами. У этого узла есть отличные от общедоступного узла свойства:

• Доступ к этому узлу возможен только по HTTPS.
  
• Этот узел не находится за пограничным сервером кэширования Akamai.
  
• Каждый запрос к этому узлу должен выполняться с использованием издательского ключа, даже если для запроса не требуется ключ. Запросы без ключа вернут ошибку 403.
  
• Если запросы создают коды состояния 403 (обычно это происходит, если вместо ключа издателя используется обычный ключ веб-API), для подключающегося IP будет установлено жёсткое ограничение на частоту запросов. Это сделано для того, чтобы убедиться в высокой доступности узла.
  
• Если вы отправляете запросы с узла, имеющего фильтр брандмауэра на исходящие запросы, добавьте DNS-адрес partner.steam-api.com в список разрешений. Если ваш брандмауэр принимает только адреса из цифр, добавьте в список разрешённых адресов следующий бесклассовый адрес: 208.64.200.0/22.
  ВНИМАНИЕ: не подключайтесь к серверам веб-API по IP. Используйте DNS-имя. Данные адреса предоставляется только для клиентов, которым нужно добавить их в список разрешённых адресов брандмауэра.

Список разрешённых IP-адресов

Мы позволяем добавлять IP-адреса в список разрешённых для вызовов веб-API. Это дополнительный слой защиты на случай, если ваш ключ веб-API попадёт в чужие руки. Его использование позволяет принимать только вызовы веб-API с разрешённых IP-адресов. Когда IP-адрес добавлен в список разрешённых, запросы с остальных адресов будут блокироваться и возвращать ответ 403 (доступ запрещён).

IP-адрес можно легко добавить в список разрешённых. На любой странице группы, у которой есть ключ веб-API, нажмите на кнопку «Управление ключом веб-API» и следуйте дальнейшим инструкциям.

Для каждого ключа веб-API существует свой список разрешённых адресов, но добавлять в него IP-адреса необязательно.

Обратите внимание: добавление в список разрешённых адресов не гарантирует защиту ключа веб-API. Никогда не передавайте никому свой ключ, а если он попал к посторонним — немедленно смените его.