Steamworks-dokumentation
Web-API-oversigt

Indledning

Steam har en HTTP-baseret web-API, som kan bruges til at få adgang til mange Steamworks-funktioner. API'en indeholder offentlige metoder, som kan tilgås fra enhver applikation, som er i stand til at lave en HTTP-anmodning, såsom en spilklient eller server. API'en indeholder også beskyttede metoder, som kræver godkendelse og er beregnet til at blive tilgået fra pålidelige backend-applikationer.

Som et eksempel bruges web-API-metoder normalt af en sikker udgiverserver til at:
  • Bekræfte en Steam-brugers oplysninger med den pågældende server
  • Tjekke, om en bruger ejer en bestemt applikation
  • Indstille eller hente en brugers statistikker, præstationer eller førertavlescore
  • Foretage køb i spil

Du kan finde en komplet liste over alt, som tilbydes af Steamworks-web-API'en i Reference for Steamworks-web-API.

Anmodningsformat

Den offentlige Steamworks-web-API kan tilgås ved at lave HTTP-anmodninger (port 80) eller HTTPS-anmodninger (port 443) til api.steampowered.com.
Hvis du er udgiver, stiller Steam også en web-API-server til rådighed for partnere på https://partner.steam-api.com. Hensigten med denne tjeneste er at have større tilgængelighed end den offentlige vært. Du bør bruge denne tjeneste til alle anmodninger, som foretages fra dine sikre servere. Se Web-API-værtsadresser samt overvejelser i forhold til firewalls for at få yderligere oplysninger.

I stil med Steamworks C++-API'en er web-API'en blevet delt op i flere grænseflader, som indeholder relaterede metoder. URI-formatet af hver API-anmodning er:
https://api.steampowered.com/<interface>/<method>/v<version>/

De fleste metoder understøtter en liste over påkrævede og valgfri parametre. Afhængigt af metoden skal disse parametre indsendes som GET- eller POST-parametre i anmodningen.

Alle anmodniger bør sendes ved at bruge HTTP1.1 og bruge SSL v3, 128 bit-kryptering, når det er muligt. Content-Type skal være application/x-www-form-urlencoded, og POST-parametrene skal være i hoveddelen af anmodningen i standardform URL-kodningsformat. Teksten skal udsendes som UTF-8.

Godkendelse

Mange web-API-metoder har adgangsbegrænsninger, som kræver en entydig nøgle. Se Godkendelse med web-API-nøgler for yderligere oplysninger.

Array-parametre

Nogle metoder forventer et array med parametre. Dette specificeres af en [0] efter teksten i parametrets navn. Når arrays sendes, vil der altid være en count-parameter, som angiver antallet af parametre i arrayet. For eksempel:
?count=2&name[0]=SomeNameHere&name[1]=SomeOtherName

Tjenestegrænseflader

Ud over de almindelige web-API-kald er der tjenestegrænseflader. Disse grænseflader fungerer meget lig de almindelige grænseflader. Den primære forskel er, at alle tjeneste-API'er vil acceptere argumenter som en enkelt JSON-blob ud over at tage dem som GET- eller POST-parametre. For at give data som JSON skal web-API-metoden kaldes med input_json-parametren indstillet som:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

Bemærk, at JSON'en skal være URL-kodet. Felterne "key" og "format" bør stadigvæk sendes som adskilte parametre, som før. POST-anmodninger understøttes også.

Du kan identificere, om en web-API er en "tjeneste" ud fra grænsefladenavnet. Hvis den ender med "service" (tjeneste) såsom IPlayerService, understøtter den denne ekstra metode til at sende parameterdata. Nogle tjenestemetoder har parametre, som er mere komplekse strukturer og kræver dette alternative inputformat.

Eksempel på forespørgsel

Det følgende eksempel henter de tre seneste nyhedsindlæg for Team Fortress 2.
Anmodningen specificerer, at svaret bør returneres som JSON og inkluderer en påkrævet app-ID-parameter (Team Fortress 2's app-ID er 440) og en valgfri antalsparameter til at begrænse antallet af resultater, som returneres.

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

Du kan udføre og se resultaterne af denne forespørgsel med dette link:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

Du kan læse mere om de specifikke kald her: ISteamNews/GetNewsForApp

Indhentning af brugerens Steam-ID

Steamworks-web-API'en identificerer individuelle brugere ved at bruge deres entydige 64-bit Steam-ID. Se Brugergodkendelse og ejerskab for at lære, hvordan man sikkert får brugerens Steam-ID.

Web-API-værtsadresser samt overvejelser i forhold til firewalls

Den offentlige web-API (api.steampowered.com) ligger bag Akamais edge cache, så de IP-adresser, du ser for navnet, vil variere alt efter, hvor du befinder dig, og igangværende tjenesteændringer. IP'erne kan ændres hurtigt og flydende, så hvis dine web-API-kald laves gennem en firewall på udgående anmodninger, skal du læse videre her.

Du bør bruge bruge partnertilstanden (https://partner.steam-api.com) til alle anmodninger, som foretages fra dine sikre servere. Denne vært har nogle andre egenskaber end den offentlige vært:
  • Denne vært kan kun tilgås via HTTPS.
  • Værten er ikke bag Akamais edge cache.
  • Hver anmodning til denne vært skal laves med din web-API-udgivernøgle – selv anmodninger, som normalt ikke behøver en nøgle. Anmodninger, som laves uden en gyldig udgivernøgle, vil returnere en 403-fejlkode.
  • 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. Dette gøres for at sikre høj tilgængelighed.
  • Hvis du laver anmodninger til denne API-tjeneste fra en vært, som har et firewallfilter på udgående anmodninger, bør du tilføje DNS-navnet "partner.steam-api.com" til din tilladelsesliste. Hvis din firewall kun understøtter numeriske adresser, skal du tilføje følgende CIDR-blok til tilladelseslisten: 208.64.200.0/22.
    BEMÆRK: Du bør ikke oprette forbindelse til web-API-servere ved brug af IP – brug i stedet DNS-navnet. Disse adresser gives kun til de klienter, som har brug for at hvidliste adresserne i deres firewalls.

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.