Introduzione

Steam offre un'API web HTTP che può essere utilizzata per accedere a molte funzioni di Steamworks. L'API contiene i metodi pubblici a cui è possibile accedere da qualsiasi applicazione in grado di effettuare una richiesta HTTP, come i client o i server di gioco. L'API racchiude inoltre metodi protetti che richiedono l'autenticazione e il cui accesso è destinato alle applicazioni di back-end attendibili.

Ad esempio, i metodi dell'API web sono spesso usati dai server attendibili degli editori per:

• Verificare le credenziali di un utente di Steam nel server stesso
  
• Verificare se un utente è in possesso di una data applicazione
  
• Impostare o recuperare le statistiche, gli achievement o la posizione in una classifica degli utenti
  
• Eseguire un acquisto in gioco

Puoi trovare una lista completa di tutte le funzionalità offerte dall'API web di Steamworks nel Riferimenti per l'API web di Steamworks.

Formato della richiesta

L'API web pubblica di Steamworks è accessibile attraverso richieste effettuate tramite HTTP (porta 80) o HTTPS (porta 443) a api.steampowered.com.
Steam fornisce agli editori anche un'API web esclusiva per i partner, accessibile su https://partner.steam-api.com. Lo scopo di questo servizio è fornire una disponibilità più elevata di quella dell'host pubblico e dovrebbe essere utilizzato per tutte le richieste effettuate dai tuoi server sicuri. Consulta Indirizzi host dell'API web e considerazioni sui firewall per maggiorni informazioni.

L'API web, allo stesso modo dell'API C++ di Steamworks, è stata suddivisa in svariate interfacce contenenti i relativi metodi. Il formato URI di ognuna delle richieste API è:
La maggior parte dei metodi supporta una lista di parametri obbligatori e opzionali. A seconda del metodo, questi parametri devono essere inoltrati nella richiesta come GET o POST.

Tutte le richieste devono essere inviate tramite HTTP 1.1 e quando possibile utilizzare una connessione TLS sicura. Il tipo di contenuto deve essere application/x-www-form-urlencoded e i parametri POST devono trovarsi nel corpo della richiesta nel formato standard per la codificazione degli URL. Il testo deve essere trasmesso in formato UTF-8.

Autenticazione

Molti metodi dell'API web presentano restrizioni di accesso e richiedono una chiave unica. Per ulteriori informazioni, consulta Autenticazione attraverso le chiavi dell'API web.

Parametri della matrice

Alcuni metodi richiedono una matrice di parametri. Ciò è specificato da un suffisso [0] sul nome del parametro. Quando si trasmettono matrici, sarà sempre presente un parametro count che specifica il numero di parametri contenuti nella matrice. Ad esempio:

Interfacce di servizio

Oltre alle normali chiamate dell'API web, vi sono anche delle interfacce di servizio. Queste interfacce funzionano in maniera molto simile a quelle standard, con la differenza principale che tutte le API di servizio accettano i loro argomenti come un singolo blob JSON oltre che riceverli come parametri GET o POST. Per passare i dati come JSON, chiama il metodo dell'API web con il parametro nput_json impostato come segue:

Nota che il JSON deve essere codificato come URL. I campi della "chiave" e del "formato" devono essere passati come parametri separati, come in precedenza. Sono supportate anche le richieste POST.

Per identificare se un'API web è un "servizio", basta verificare il nome dell'interfaccia: se finisce in "Service", come ad esempio IPlayerService, significa che l'API supporta questo ulteriore metodo di passaggio dei dati dei parametri. Alcuni metodi di servizio hanno parametri dalle strutture più complesse che richiedono questo formato alternativo di input.

Esempio di richiesta

Il seguente esempio recupera le 3 notizie più recenti riguardo Team Fortress 2.
La richiesta specifica che la risposta deve essere restituita come JSON e include la richiesta del parametro dell'appid (l'appID di Team Fortress 2 è 440) e un parametro opzionale di conteggio per limitare il numero di risultati restituiti.


Puoi eseguire e visualizzare i risultati di questa richiesta tramite questo link:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

Per ulteriori informazioni su questa chiamata, consulta: ISteamNews/GetNewsForApp.

Ottenere l'ID di Steam dell'utente

L'API web di Steamworks identifica ogni utente attraverso il loro ID di Steam unico a 64 bit. Per imparare a ottenere in maniera sicura l'ID di Steam di un utente, consulta Autenticazione dell'utente e verifica della proprietà.

Indirizzi host dell'API web e considerazioni sui firewall

L'API web pubblica (api.steampowered.com) è dietro la cache edge Akamai, così che gli indirizzi IP che vedrai per ogni nome varieranno in base a dove ti trovi e a cambiamenti nel servizio. Gli IP possono essere in continuo cambiamento, quindi se le tue chiamate all'API web sono effettuate attraverso un firewall quando inviano una richiesta, continua a leggere.

Utilizza il nodo esclusivo per i partner (https://partner.steam-api.com) per tutte le richieste provenienti dai tuoi server sicuri. Questo host ha delle caratteristiche diverse da quello pubblico:

• È accessibile solo tramite HTTPS.
  
• Non si trova dietro la cache edge di Akamai.
  
• Tutte le richieste a questo host devono essere effettuate con la tua chiave dell'API web da editore, incluse quelle che di solito non richiedono una chiave. Le richieste effettuate senza una chiave da editore valida restituiranno l'errore 403.
  
• Le richieste che generano l'errore 403, causato solitamente dall'utilizzo di una normale chiave dell'API web invece che quella da editore, risulteranno in forti limitazioni dell'IP che le invia, in modo da garantire un'alta disponibilità.
  
• Se invierai richieste a questo servizio API da un host che applica un filtro firewall alle richieste in uscita, aggiungi il DNS "partner.steam-api.com" alla lista dei consentiti. Se il tuo firewall supporta solo indirizzi numerici, aggiungi questo blocco CDR alla lista dei consentiti: 208.64.200.0/22.
  NOTA: Non connetterti ai server dell'API web tramite IP, ma tramite il nome DNS. Questi indirizzi sono forniti solo per i clienti che hanno bisogno di aggiungerli alle loro liste dei consentiti dal loro firewall.

Inserire indirizzi IP nella lista dei consentiti

Consentiamo di aggiungere indirizzi IP alla lista dei consentiti per le chiamate all'API web. Ciò rappresenta un ulteriore livello di sicurezza nel caso in cui la tua chiave dell'API web sia compromessa, poiché fa sì che riescano solo le chiamate all'API web provenienti da indirizzi IP consentiti. Una volta che un indirizzo IP viene consentito, tutte le altre richieste da indirizzi non consentiti sranno bloccate e restituiranno l'errore 403 ("Forbidden response", risposta non consentita).

Aggiungere indirizzi IP alla lista dei consentiti è semplice. Da qualunque pagina di un gruppo provvisto di chiave API web, clicca su "Gestisci chiave API web" e segui le istruzioni.

Ogni chiave API web ha la sua lista dei consentiti e aggiungere indirizzi IP alla lista non è richiesto.

Nota: l'utilizzo della lista dei consentiti non garantisce la sicurezza della chiave dell'API web. Proteggi la tua chiave, non condividerla con nessuno e cambiala immediatamente se è compromessa.