Вступ

Steam має вбудовний веб-API на основі HTTP, котрий можна використовувати для доступу до багатьох функцій Steamworks. API містить публічні методи, доступ до яких може отримати будь-який застосунок, що може надіслати HTTP-запит, як-от ігровий клієнт чи сервер. API також містить захищені методи, які потребують автентифікації. Доступ до них можуть отримати довірені серверні застосунки.

Наприклад, методи веб-API зазвичай використовуються захищеним сервером видавця для:

• Перевірки даних акаунта користувача Steam на цьому сервері.
  
• Перевірки володіння користувачем певним застосунком.
  
• Встановлення чи отримання даних про статистику, досягнення й показники користувача в таблиці лідерів.
  
• Виконання внутрішньоігрових придбань.

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

Формат запиту

Публічні веб-API Steamworks доступні через запити HTTP (порт 80) чи HTTPS (порт 443) до api.steampowered.com.
Якщо ви видавець, то Steam також надає сервер веб-API лише для партнерів: https://partner.steam-api.com. Цей сервер доступніший за публічний, тож вам варто використовувати його для всіх запитів від ваших захищених серверів. Додаткова інформація розміщена ось тут.

Як і API Steamworks на C++, веб-API розділений на багато інтерфейсів, які містять пов’язані методи. Формат URI для запиту до API такий:
Більшість методів підтримують певний перелік обов’язкових і необов’язкових параметрів. Залежно від методу ці параметри потрібно передавати в запиті як GET або POST.

Усі запити слід надсилати через HTTP 1.1 і за можливості використовувати захищене підключення TLS. Content-Type повинен бути application/x-www-form-urlencoded, а параметри POST повинні бути в тілі запиту в стандартному форматі URL-кодування. Текст потрібно надсилати як UTF-8.

Автентифікація

Багато методів веб-API мають обмеження доступу, що вимагає унікальний ключ. Докладнішу інформацію читайте ось тут.

Масиви параметрів

Деякі методи очікують на масиви параметрів. На це вказує постфікс [0] у назві параметра. Під час передавання масивів завжди існуватиме параметр count, який визначає кількість параметрів у масиві. Наприклад:

Службові інтерфейси

Окрім звичайних викликів до веб-API, існують службові інтерфейси. Ці інтерфейси дуже схожі на звичайні, але основна відмінність полягає в тому, що всі службові 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

Отримання SteamID користувача

Веб-API Steamworks ідентифікує окремих користувачів за допомогою їхніх унікальних 64-бітних SteamID. Безпечне отримання користувацького SteamID описано ось тут.

Міркування стосовно адрес вузлів веб-API та брандмауерів

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

Для всіх запитів зі своїх захищених серверів вам слід використовувати вузол лише для партнерів (https://partner.steam-api.com). Цей вузол має деякі властивості, що відрізняються від загальнодоступного вузла:

• Доступ можливий лише через HTTPS.
  
• Вузол знаходиться не за межовим сервером кешування Akamai.
  
• Кожен запит до цього вузла повинен здійснюватися за допомогою ключа веб-API, навіть якщо для запиту зазвичай не потрібен ключ. Запити без дійсного ключа повернуться помилку з кодом 403.
  
• Якщо запити генерують коди стану 403, що зазвичай трапляється під час використання звичайного ключа веб-API замість ключа видавця, то для IP-підключення буде встановлено жорстке обмеження на частоту запитів. Це необхідно для забезпечення високої доступності.
  
• Якщо ви надсилаєте запити до цього сервісу API з вузла, який має фільтр-брандмауер на вихідні запити, то додайте DNS-адресу partner.steam-api.com у ваш список дозволів. Якщо ваш брандмауер підтримує цифрові адреси, то додайте в список дозволів наступний CIDR:208.64.200.0/22.
  ПРИМІТКА: не варто підключатися до серверів веб-API за допомогою IP, використовуйте DNS-ім’я. Ці адреси надаються лише тим клієнтам, яким потрібно додати їх у список виключень брандмауерів.

Список дозволів для IP-адрес

Ми дозволяємо додавати в список дозволів IP-адреси для викликів веб-API. Це додатковий шар захисту на випадок, якщо ваш ключ веб-API буде викрадено, оскільки він перевіряє, щоби успішними ставали лише виклики веб-API з IP-адрес у білому списку. Коли в список дозволів додається якась IP-адреса, то всі запити з інших адрес блокуватимуться й повертатимуть помилку 403 (доступ заборонено).

Додавання IP-адрес до білого списку є простим. На будь-якій сторінці групи, що має ключ веб-API, клацніть на кнопку «Управління ключем веб-API» й дотримуйтеся інструкцій.

Кожен ключ веб-API має власний список дозволів і додавати в цей список щось необов’язково.

Примітка: додавання у список дозволів не гарантує захист ключа веб-API. Захищайте свій ключ самостійно: не поширюйте його та змінюйте одразу, якщо він потрапив до сторонніх осіб.