Module: WebApi

Defined in:
lib/steam/community/web_api.rb

Overview

This module provides functionality for accessing Steam’s Web API

The Web API requires you to register a domain with your Steam account to acquire an API key. See steamcommunity.com/dev for further details.

Author:

  • Sebastian

Constant Summary collapse

@@api_key = 
nil
@@secure = 
true

Class Method Summary collapse

Class Method Details

.api_key ⇒ String

Returns the Steam Web API key currently used by Steam Condenser

Returns:

  • (String) —

    The currently active Steam Web API key



26
27
28
 
# File 'lib/steam/community/web_api.rb', line 26

def self.api_key
  @@api_key
end

.api_key=(api_key) ⇒ Object

Sets the Steam Web API key

Parameters:

  • api_key (String) —

    The 128bit API key as a hexadecimal string that has to be requested from steamcommunity.com/dev

Raises:

  • (WebApiError) —

    if the given API key is not a valid 128bit hexadecimal string



36
37
38
39
40
41
42
 
# File 'lib/steam/community/web_api.rb', line 36

def self.api_key=(api_key)
  unless api_key.nil? || api_key.match(/^[0-9A-F]{32}$/)
    raise WebApiError, :invalid_key
  end

  @@api_key = api_key
end

.get(format, interface, method, version = 1, params = {}) ⇒ String

Fetches data from Steam Web API using the specified interface, method and version. Additional parameters are supplied via HTTP GET. Data is returned as a string in the given format.

Parameters:

  • format (Symbol) —

    The format to load from the API (‘:json`, `:vdf`, or `:xml`)

  • interface (String) —

    The Web API interface to call, e.g. ‘ISteamUser`

  • method (String) —

    The Web API method to call, e.g. ‘GetPlayerSummaries`

  • version (Fixnum) (defaults to: 1) —

    The API method version to use

  • params (Hash<Symbol, Object>) (defaults to: {}) —

    Additional parameters to supply via HTTP GET

Returns:

  • (String) —

    The data as replied by the Web API in the desired format

Raises:

  • (WebApiError) —

    if the request to Steam’s Web API fails



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/steam/community/web_api.rb', line 117

def self.get(format, interface, method, version = 1, params = {})
  version = version.to_s.rjust(4, '0')
  params = { :key => WebApi.api_key }.merge params unless WebApi.api_key.nil?
  params = { :format => format }.merge params
  protocol = @@secure ? 'https' : 'http'
  url = "#{protocol}://api.steampowered.com/#{interface}/#{method}/v#{version}/" +
        '?' + params.map { |k,v| "#{k}=#{v}" }.join('&')

  begin
    if $DEBUG
      debug_url = @@api_key.nil? ? url : url.gsub(@@api_key, 'SECRET')
      puts "Querying Steam Web API: #{debug_url}" if $DEBUG
    end
    open(url, { 'Content-Type' => 'application/x-www-form-urlencoded' ,:proxy => true }).read
  rescue OpenURI::HTTPError
    status = $!.io.status[0]
    status = [status, ''] unless status.is_a? Array
    raise WebApiError, :unauthorized if status[0].to_i == 401
    raise WebApiError.new :http_error, status[0].to_i, status[1]
  end
end

.interfaces ⇒ Array<Hash>

Returns a raw list of interfaces and their methods that are available in Steam’s Web API

This can be used for reference when accessing interfaces and methods that have not yet been implemented by Steam Condenser.

Returns:

  • (Array<Hash>) —

    The list of interfaces and methods



58
59
60
61
 
# File 'lib/steam/community/web_api.rb', line 58

def self.interfaces
  data = json 'ISteamWebAPIUtil', 'GetSupportedAPIList'
  MultiJson.load(data, { :symbolize_keys => true })[:apilist][:interfaces]
end

.json(interface, method, version = 1, params = {}) ⇒ String

Fetches JSON data from Steam Web API using the specified interface, method and version. Additional parameters are supplied via HTTP GET. Data is returned as a JSON-encoded string.

Parameters:

  • interface (String) —

    The Web API interface to call, e.g. ‘ISteamUser`

  • method (String) —

    The Web API method to call, e.g. ‘GetPlayerSummaries`

  • version (Fixnum) (defaults to: 1) —

    The API method version to use

  • params (Hash<Symbol, Object>) (defaults to: {}) —

    Additional parameters to supply via HTTP GET

Returns:

  • (String) —

    The raw JSON data replied to the request

Raises:

  • (WebApiError) —

    if the request to Steam’s Web API fails



75
76
77
 
# File 'lib/steam/community/web_api.rb', line 75

def self.json(interface, method, version = 1, params = {})
  get :json, interface, method, version, params
end

.json!(interface, method, version = 1, params = {}) ⇒ Hash<Symbol, Object>

Fetches JSON data from Steam Web API using the specified interface, method and version. Additional parameters are supplied via HTTP GET. Data is returned as a Hash containing the JSON data.

Parameters:

  • interface (String) —

    The Web API interface to call, e.g. ‘ISteamUser`

  • method (String) —

    The Web API method to call, e.g. ‘GetPlayerSummaries`

  • version (Fixnum) (defaults to: 1) —

    The API method version to use

  • params (Hash<Symbol, Object>) (defaults to: {}) —

    Additional parameters to supply via HTTP GET

Returns:

  • (Hash<Symbol, Object>) —

    The JSON data replied to the request

Raises:

  • (WebApiError) —

    if the request to Steam’s Web API fails



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/steam/community/web_api.rb', line 91

def self.json!(interface, method, version = 1, params = {})
  data = json interface, method, version, params
  result = MultiJson.load(data, { :symbolize_keys => true })[:result]

  status = result[:status]
  if status != 1
    raise WebApiError.new :status_bad, status, result[:statusDetail]
  end

  result
end

.secure=(secure) ⇒ Object

Sets whether HTTPS should be used for the communication with the Web API

Parameters:

  • secure (Boolean) —

    Whether to use HTTPS



47
48
49
 
# File 'lib/steam/community/web_api.rb', line 47

def self.secure=(secure)
  @@secure = !!secure
end