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) —

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

Raises:

  • (ArgumentError) 


58
59
60
61
62
63
64
65
66
 
# File 'lib/osm/api.rb', line 58

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



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/osm/api.rb', line 106

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

.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) —

    wether 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

Instance Method Details

#api_id ⇒ String

Get the API ID

Returns:

  • (String) 


77
78
79
 
# File 'lib/osm/api.rb', line 77

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

#api_name ⇒ String

Get the API name

Returns:

  • (String) 


71
72
73
 
# File 'lib/osm/api.rb', line 71

def api_name
  @@api_details[@site][:name]
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



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

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:



123
124
125
126
127
 
# File 'lib/osm/api.rb', line 123

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

#site ⇒ Symbol

Get the site this Api currently uses

Returns:

  • (Symbol) —

    :osm or :ogm



87
88
89
 
# File 'lib/osm/api.rb', line 87

def site
  @site
end

#to_i ⇒ Object 



80
81
82
 
# File 'lib/osm/api.rb', line 80

def to_i
  api_id
end

#user_id ⇒ String

Get the current user_id

Returns:

  • (String) 


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

def user_id
  @user_id
end