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',
  :osm_staging => 'http://staging.onlinescoutmanager.co.uk',
  :migration => 'https://migration.onlinescoutmanager.com'
}
@@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)

82
83
84
85
86
87
88
89
90
# File 'lib/osm/api.rb', line 82

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::Api::BASE_URLS.keys.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


130
131
132
133
134
135
136
137
138
139
140
# File 'lib/osm/api.rb', line 130

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)

156
157
158
159
# File 'lib/osm/api.rb', line 156

def self.base_url(site=@@site)
  raise ArgumentError, "Invalid site" unless Osm::Api::BASE_URLS.keys.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)

33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# File 'lib/osm/api.rb', line 33

def self.configure(options)
  unless options[:i_know].eql?(:unsupported)
    raise Osm::Error, 'The OSM gem is now unsupported. ' \
                      'To continue using it append "i_know: :unsupported" to your passed options. ' \
                      "See #{File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'UNSUPPORTED.md'))} for more details."
  end

  raise ArgumentError, ':default_site does not exist in options hash or is invalid, this should be set to either :osm or :ogm' unless Osm::Api::BASE_URLS.keys.include?(options[:default_site])
  raise ArgumentError, ":#{options[:default_site]} does not exist in options hash" if options[options[:default_site]].nil?

  Osm::Api::BASE_URLS.keys.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}" unless api_data.key?(key)
      end
    end
  end

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

.debugObject

The debug option

Returns:

  • Boolean whether debugging output is enabled


73
74
75
# File 'lib/osm/api.rb', line 73

def self.debug
  @@debug
end

.debug=(debug) ⇒ Object

Configure the debug option

Parameters:

  • debug (Boolean)

    whether to display debugging information

Returns:

  • nil


67
68
69
# File 'lib/osm/api.rb', line 67

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

Instance Method Details

#api_idString

Get the API ID

Returns:

  • (String)

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

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

#api_nameString

Get the API name

Returns:

  • (String)

95
96
97
# File 'lib/osm/api.rb', line 95

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


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

def base_url(site=@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


225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
# File 'lib/osm/api.rb', line 225

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

  all_permissions = Hash.new
  get_user_roles(options).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

#get_user_roles(*args) ⇒ Array<Hash>

Get API user's roles in OSM

Returns:

  • (Array<Hash>)

    data returned by OSM


182
183
184
185
186
187
188
# File 'lib/osm/api.rb', line 182

def get_user_roles(*args)
  begin
    get_user_roles!(*args)
  rescue Osm::NoActiveRoles
    return []
  end
end

#get_user_roles!(options = {}) ⇒ Array<Hash>

Get API user's roles in OSM

Returns:

  • (Array<Hash>)

    data returned by OSM


195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
# File 'lib/osm/api.rb', line 195

def get_user_roles!(options={})
  cache_key = ['user_roles', @user_id]

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

  begin
    data = perform_query('api.php?action=getUserRoles')
    unless data.eql?(false)
      # false equates to no roles
      Osm::Model.cache_write(self, cache_key, data)
      return data
    end
    fail Osm::NoActiveRoles, "You do not have any active roles in OSM."

  rescue Osm::Error => e
    if e.message.eql?('false')
      fail Osm::NoActiveRoles, "You do not have any active roles in OSM."
    else
      raise e
    end
  end

end

#perform_query(url, api_data = {}, raw = false) ⇒ 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


172
173
174
175
176
177
# File 'lib/osm/api.rb', line 172

def perform_query(url, api_data={}, raw=false)
  self.class.perform_query(@site, url, api_data.merge({
    'userid' => @user_id,
    'secret' => @user_secret,
  }), raw)
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:


147
148
149
150
151
# File 'lib/osm/api.rb', line 147

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


246
247
248
249
250
# File 'lib/osm/api.rb', line 246

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

#siteSymbol

Get the site this Api currently uses

Returns:

  • (Symbol)

    :osm or :ogm


111
112
113
# File 'lib/osm/api.rb', line 111

def site
  @site
end

#to_iObject


104
105
106
# File 'lib/osm/api.rb', line 104

def to_i
  api_id
end

#user_idString

Get the current user_id

Returns:

  • (String)

118
119
120
# File 'lib/osm/api.rb', line 118

def user_id
  @user_id
end