Class: Osm::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/osm/api.rb

Constant Summary collapse

BASE_URLS = 
{
  :osm => 'https://www.onlinescoutmanager.co.uk',
  :ogm => 'http://www.onlineguidemanager.co.uk',
}
@@site =

Default options

nil
@@debug =

Used to make requests from an instance

false
@@api_details =

Puts helpful information whilst connected to OSM/OGM

{:osm=>{}, :ogm=>{}}

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(user_id, secret, site = @@site) ⇒ Object

Initialize a new API connection

Parameters:

  • user_id (String) —

    OSM userid of the user to act as (get this by using the authorize method)

  • secret (String) —

    OSM secret of the user to act as (get this by using the authorize method)

  • site (Symbol) (defaults to: @@site) —

    Whether to use OSM (:osm) or OGM (:ogm), defaults to the value set for the class

Raises:

  • (ArgumentError) 


71
72
73
74
75
76
77
78
79
 
# File 'lib/osm/api.rb', line 71

def initialize(user_id, secret, site=@@site)
  raise ArgumentError, 'You must pass a secret (get this by using the authorize method)' if secret.nil?
  raise ArgumentError, 'You must pass a user_id (get this by using the authorize method)' if user_id.nil?
  raise ArgumentError, 'site is invalid, if passed it should be either :osm or :ogm, if not passed then you forgot to run Api.configure' unless [:osm, :ogm].include?(site)

  @site = site
  set_user(user_id, secret)
  nil
end

Class Method Details

.authorize(site = @@site, email, password) ⇒ Hash

Get the userid and secret to be able to act as a certain user on the OSM/OGM system

Parameters:

  • site (Symbol) (defaults to: @@site) —

    The site to use either :osm or :ogm (defaults to whatever was set in the configure method)

  • email (String) —

    The login email address of the user on OSM

  • password (String) —

    The login password of the user on OSM

Returns:

  • (Hash) —

    a hash containing the following keys:

    • :user_id - the userid to use in future requests

    • :secret - the secret to use in future requests



119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/osm/api.rb', line 119

def self.authorize(site=@@site, email, password)
  api_data = {
    'email' => email,
    'password' => password,
  }
  data = perform_query(site, 'users.php?action=authorise', api_data)
  return {
    :user_id => data['userid'],
    :secret => data['secret'],
  }
end

.base_url(site = @@site) ⇒ String

Get the base URL for requests to OSM/OGM

Parameters:

  • site (Symbol) (defaults to: @@site) —

    For OSM or OGM (:osm or :ogm)

Returns:

  • (String) —

    The base URL for requests

Raises:

  • (ArgumentError) 


145
146
147
148
 
# File 'lib/osm/api.rb', line 145

def self.base_url(site=@@site)
  raise ArgumentError, "Invalid site" unless [:osm, :ogm].include?(site)
  BASE_URLS[site]
end

.configure(options) ⇒ Object

Configure the API options used by all instances of the class

Parameters:

  • options (Hash)
  • options[:osm] (Hash) —

    a customizable set of options

  • options[:ogm] (Hash) —

    a customizable set of options

Options Hash (options):

  • :default_site (Symbol) —

    whether to use OSM (if :osm) or OGM (if :ogm)

  • :osm (Hash) — default: optional but :osm_api or :ogm_api must be present —

    the api data for OSM

  • :ogm (Hash) — default: optional but :osm_api or :ogm_api must be present —

    the api data for OGM

  • :debug (Boolean) —

    if true debugging info is output (optional, default = false)

Returns:

  • nil

Raises:

  • (ArgumentError) 


31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/osm/api.rb', line 31

def self.configure(options)
  raise ArgumentError, ':default_site does not exist in options hash or is invalid, this should be set to either :osm or :ogm' unless [:osm, :ogm].include?(options[:default_site])
  raise ArgumentError, ':osm and/or :ogm must be present' if options[:osm].nil? && options[:ogm].nil?
  [:osm, :ogm].each do |api_key|
    if options[api_key]
      api_data = options[api_key]
      raise ArgumentError, ":#{api_key} must be a Hash" unless api_data.is_a?(Hash)
      [:id, :token, :name].each do |key|
        raise ArgumentError, ":#{api_key} must contain a key :#{key}" if api_data[key].nil?
      end
    end
  end

  @@site = options[:default_site]
  @@debug = !!options[:debug]
  @@api_details = {
    :osm => (options[:osm] || {}),
    :ogm => (options[:ogm] || {}),
  }
  nil
end

.debug ⇒ Object

The debug option

Returns:

  • Boolean whether debugging output is enabled



62
63
64
 
# File 'lib/osm/api.rb', line 62

def self.debug
  @@debug
end

.debug=(debug) ⇒ Object

Configure the debug option

Parameters:

  • debug (Boolean) —

    whether to display debugging information

Returns:

  • nil



56
57
58
 
# File 'lib/osm/api.rb', line 56

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

Instance Method Details

#api_id ⇒ String

Get the API ID

Returns:

  • (String) 


90
91
92
 
# File 'lib/osm/api.rb', line 90

def api_id
  @@api_details[@site][:id]
end

#api_name ⇒ String

Get the API name

Returns:

  • (String) 


84
85
86
 
# File 'lib/osm/api.rb', line 84

def api_name
  @@api_details[@site][:name]
end

#base_url(site = @site) ⇒ String

Get the base URL for requests to OSM.OGM

Parameters:

  • site (defaults to: @site) —

    For OSM or OGM (:osm or :ogm), defaults to the default for this api object

Returns:

  • (String) —

    The base URL for requests

Raises:

  • (ArgumentError) 


153
154
155
156
 
# File 'lib/osm/api.rb', line 153

def base_url(site=@site)
  raise ArgumentError, "Invalid site" unless [:osm, :ogm].include?(site)
  self.class.base_url(site)
end

#get_user_permissions(options = {}) ⇒ Object

Get API user’s permissions

Returns:

  • nil if an error occured or the user does not have access to that section

  • (Hash) —

    => permissions_hash



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/osm/api.rb', line 173

def get_user_permissions(options={})
  cache_key = ['permissions', user_id]

  if !options[:no_cache] && Osm::Model.cache_exist?(self, cache_key)
    return Osm::Model.cache_read(self, cache_key)
  end

  data = perform_query('api.php?action=getUserRoles')

  all_permissions = Hash.new
  data.each do |item|
    unless item['section'].eql?('discount')  # It's not an actual section
      all_permissions.merge!(Osm::to_i_or_nil(item['sectionid']) => Osm.make_permissions_hash(item['permissions']))
    end
  end
  Osm::Model.cache_write(self, cache_key, all_permissions)

  return all_permissions
end

#perform_query(url, api_data = {}) ⇒ Hash, ...

Make a query to the OSM/OGM API

Parameters:

  • url (String) —

    The script on the remote server to invoke

  • api_data (Hash) (defaults to: {}) —

    A hash containing the values to be sent to the server in the body of the request

Returns:

  • (Hash, Array, String) —

    the parsed JSON returned by OSM



162
163
164
165
166
167
 
# File 'lib/osm/api.rb', line 162

def perform_query(url, api_data={})
  self.class.perform_query(@site, url, api_data.merge({
    'userid' => @user_id,
    'secret' => @user_secret,
  }))
end

#set_user(user_id, secret) ⇒ Osm::Api

Set the OSM user to make future requests as

Parameters:

  • user_id (String) —

    The OSM userid to use (get this using the authorize method)

  • secret (String) —

    The OSM secret to use (get this using the authorize method)

Returns:



136
137
138
139
140
 
# File 'lib/osm/api.rb', line 136

def set_user(user_id, secret)
  @user_id = user_id
  @user_secret = secret
  return self
end

#set_user_permissions(section, permissions) ⇒ Object

Set access permission for an API user for a given Section

Parameters:

  • section (Section, Fixnum) —

    The Section to set permissions for

  • permissions (Hash) —

    The permissions Hash



196
197
198
199
200
 
# File 'lib/osm/api.rb', line 196

def set_user_permissions(section, permissions)
  key = ['permissions', user_id]
  permissions = get_user_permissions.merge(section.to_i => permissions)
  Osm::Model.cache_write(self, key, permissions)
end

#site ⇒ Symbol

Get the site this Api currently uses

Returns:

  • (Symbol) —

    :osm or :ogm



100
101
102
 
# File 'lib/osm/api.rb', line 100

def site
  @site
end

#to_i ⇒ Object 



93
94
95
 
# File 'lib/osm/api.rb', line 93

def to_i
  api_id
end

#user_id ⇒ String

Get the current user_id

Returns:

  • (String) 


107
108
109
 
# File 'lib/osm/api.rb', line 107

def user_id
  @user_id
end