Class: R43::Connection

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

Overview

Implements the 43 Things API. This is where you actually instantiate objects.

require 'r43'
connection = R43::Connection.new(<api_key>)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key, proxy_addr = nil, proxy_port = nil, proxy_user = nil, proxy_pass = nil) ⇒ Connection

Returns a new instance of Connection.



96
97
98
99
100
 
# File 'lib/r43.rb', line 96

def initialize(key, proxy_addr=nil, proxy_port=nil, 
               proxy_user=nil, proxy_pass=nil)
  @service = R43::Service.new(key, proxy_addr, proxy_port,
                              proxy_user, proxy_pass)
end

Instance Attribute Details

#response ⇒ Object (readonly)

Returns the value of attribute response.



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

def response
  @response
end

#service ⇒ Object (readonly)

Returns the value of attribute service.



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

def service
  @service
end

Instance Method Details

#authentication_test(username, password) ⇒ Object

Implements the authentication_test method from the General API. returns “true” if the connection works. Only uses the cleartext username and password at this point

require 'r43'
connection = R43::Connection.new(<api_key>)
response = connection.authentication_test(<username>,<password>)

– This really needs ATOM style authentication to work properly ++



170
171
172
173
 
# File 'lib/r43.rb', line 170

def authentication_test(username, password)
  xml = _get_response("authentication_test?username=#{username}&password=#{password}").xml
  xml.elements["authentication_test"].text
end

#echo ⇒ Object

Implements the echo method from the General API. Returns a hash with the keys; api_key, action, controller 

require 'r43'
connection = R43::Connection.new(<api_key>)
response = connection.echo



145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/r43.rb', line 145

def echo()
  xml = _get_response("echo").xml
  response = {
    "api_key" =>  
      xml.elements["parameters"].elements["api_key"].text,
    "action" =>
      xml.elements["parameters"].elements["action"].text,
    "controller" =>
      xml.elements["parameters"].elements["controller"].text
  }
end

#get_city(id) ⇒ Object

Implements the get_city method of the Cities API

require 'r43'
connection = R43::Connection.new(<api_key>)
city = connection.get_city(<id>)



481
482
483
 
# File 'lib/r43.rb', line 481

def get_city(id)
  store_and_return(_get_response("get_city?id=#{id}").city)
end

#get_citys_people(id, optional = {}) ⇒ Object

Implements the get_citys_people method of the Cities API

require 'r43'
connection = R43::Connection.new(<api_key>)
people = connection.get_citys_people(<id>)



493
494
495
496
497
498
499
 
# File 'lib/r43.rb', line 493

def get_citys_people(id, optional={})
  params = "id=#{id}"
  params += "&offset=#{optional["offset"]}" if optional["offset"]
  params += "&max=#{optional["max"]}" if optional["max"]

  store_and_return(_get_response("get_citys_people?#{params}").people)
end

#get_entry(id) ⇒ Object

Implements the get_entry method of the Entries API and returns an Entry object.

require 'r43'
connection = R43::Connection.new(<api_key>)
entry = connection.get_entry(<id>)



458
459
460
 
# File 'lib/r43.rb', line 458

def get_entry(id)
  store_and_return(_get_response("get_entry?id=#{id}").entry)
end

#get_goal_by_id(id) ⇒ Object

Implements the get_goal_by_id method from the Goals API. Returns a Goal object.

require 'r43'
connection = R43::Connection.new(<api_key>)
goal = connection.get_goal_by_id(255)



183
184
185
 
# File 'lib/r43.rb', line 183

def get_goal_by_id(id)
  store_and_return(_get_response("get_goal_by_id?id=#{id}").goal)
end

#get_goal_by_name(name) ⇒ Object

Implements the get_goal_by_name method from the Goals API. Returns a Goal object

require 'r43'
connection = R43::Connection.new(<api_key>)
goal = connection.get_goal_by_name(<name>)



196
197
198
199
 
# File 'lib/r43.rb', line 196

def get_goal_by_name(name)
  name = name.gsub!(/\s/, '+')
  store_and_return(_get_response("get_goal_by_name?name=#{name}").goal)
end

#get_goals_entries(id, optional = {}) ⇒ Object

Implements the get_goals_entries method from the Goals API and returns an array of Entry objects

require 'r43'
connection = R43::Connection.new(<api_key>)
entries = connection.get_goals_entries(<id>,[{["offset" => <offset>], 
                                           ["max" => <max>], 
                                           ["view" => <view>]}])



270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/r43.rb', line 270

def get_goals_entries(id, optional={})
  string = "id=#{id}"
  if optional["offset"] then
    string += "&offset=#{optional["offset"]}"
  end
  if optional["max"] then
    string += "&max=#{optional["max"]}"
  end
  if optional["view"] then
    string += "&view=#{optional["view"]}"
  end
  
  store_and_return(_get_response("get_goals_entries?#{string}").entries)
end

#get_goals_people(id, optional = {}) ⇒ Object

Implements the get_goals_people method from the Goals API and returns an array of Person objects

require 'r43'
connection = R43::Connection.new(<api_key>)
people = connection.get_goals_people(<id>[,
                                  {["offset" => <offset>], 
                                   ["max" => <max>]}])



248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/r43.rb', line 248

def get_goals_people(id, optional={})
  string = "id=#{id}"
  if optional["offset"] then
    string += "&offset=#{optional["offset"]}"
  end
  if optional["max"] then
    string += "&max=#{optional["max"]}"
  end
  
  store_and_return(_get_response("get_goals_people?#{string}").people)
end

#get_goals_similarities(id) ⇒ Object

Implements the get_goals_similarities method from the Goals API and returns an array of Goal objects

require 'r43'
connection = R43::Connection.new(<api_key>)
goals = connection.get_goals_similarities(<id>)



211
212
213
 
# File 'lib/r43.rb', line 211

def get_goals_similarities(id)
  store_and_return(_get_response("get_goals_similarities?id=#{id}").goals)
end

#get_person(id, use_flickr = false) ⇒ Object

Implements the get_person method from the People API and returns a Person object. If the optional true or false value is set to true, the username is treated as a flickr username instead of a 43 Things username. If the value is false or not set, the username is treated as a 43 Things username.

require 'r43'
connection = R43::Connection.new(<api_key>)
person = connection.get_person(<username>[, <true|false>])



327
328
329
330
331
332
333
334
 
# File 'lib/r43.rb', line 327

def get_person(id,use_flickr=false)
  if (use_flickr)
    id_cmd = "flickr_username"
  else
    id_cmd = "id"
  end
  store_and_return(_get_response("get_person?#{id_cmd}=#{id}").person)
end

#get_persons_completed_things(username, options = {}) ⇒ Object

Implements get_persons_completed_things from the People API and returns a Person object with completed_goals populated.

require 'r43'
connection = R43::Connection.new(<api_key>)
person = connection.get_persons_completed_things("erik")
completed_goals = person.completed_goals



345
346
347
348
 
# File 'lib/r43.rb', line 345

def get_persons_completed_things(username, options={})
  # TODO: add flickr_username handling
  store_and_return(_get_response("get_persons_completed_things?id=#{username}").person)
end

#get_persons_entries(username, options = {}) ⇒ Object

Implements get_persons_entries from the People API and returns an array of the person’s entries. This method sets connection.response and configures paging via connection.

Currently broken. The web service never returns entries.

require 'r43'
connection = R43::Connection.new(<api_key>)
entries = connection.get_persons_completed_things(<username>)
entries += connection.more



362
363
364
365
 
# File 'lib/r43.rb', line 362

def get_persons_entries(username, options={})
  # TODO: add flickr_username handling
  store_and_return(_get_response("get_persons_entries?id=#{username}").entries)
end

#get_persons_neighbors(username, options = {}) ⇒ Object

Implements get_persons_neighbors from the People API and returns an array of people. The array may be paginated.

require 'r43'
connection = R43::Connection.new(<api_key>)
people = connection.get_persons_neighborss(<username>
                                        [, options])
people += connection.more



413
414
415
416
417
 
# File 'lib/r43.rb', line 413

def get_persons_neighbors(username, options={})
  # TODO: add flickr_username handling
  # TODO: add paging options
  store_and_return(_get_response("get_persons_neighbors?id=#{username}").people)
end

#get_persons_progress_on_goal(username, goal_id, options = {}) ⇒ Object

Implements get_persons_progress_on_goal from the People API and returns an array of entries for the goal. The entries may be paginated.

require 'r43'
connection = R43::Connection.new(<api_key>)
entries = connection.get_persons_progress_on_goal(<username>, goal_id
                                               [, options])
entries += connection.more



378
379
380
381
 
# File 'lib/r43.rb', line 378

def get_persons_progress_on_goal(username, goal_id, options={})
  # TODO: add flickr_username handling
  store_and_return(_get_response("get_persons_progress_on_goal?id=#{username}&goal_id=#{goal_id}").entries)
end

#get_persons_tag_cloud(username, options = {}) ⇒ Object

Implements get_persons_tag_cloud from the People API and returns an array of tags.

require 'r43'
connection = R43::Connection.new(<api_key>)
tags = connection.get_persons_tag_cloud(<username>
                                     [, options])



444
445
446
447
 
# File 'lib/r43.rb', line 444

def get_persons_tag_cloud(username, options={})
  # TODO: add flickr_username handling
  store_and_return(_get_response("get_persons_tag_cloud?id=#{username}").tags)
end

#get_persons_tags(username, options = {}) ⇒ Object

Implements get_persons_tags from the People API and returns an array of tags.

require 'r43'
connection = R43::Connection.new(<api_key>)
tags = connection.get_persons_tags(<username>
                                [, options])



429
430
431
432
 
# File 'lib/r43.rb', line 429

def get_persons_tags(username, options={})
  # TODO: add flickr_username handling
  store_and_return(_get_response("get_persons_tags?id=#{username}").tags)
end

#get_persons_teammates(username, options = {}) ⇒ Object

Implements get_persons_teammates from the People API and returns an array of people. The people may be paginated.

require 'r43'
connection = R43::Connection.new(<api_key>)
people = connection.get_persons_teammates(<username>
                                       [, options])
people += connection.more



395
396
397
398
399
 
# File 'lib/r43.rb', line 395

def get_persons_teammates(username, options={})
  # TODO: add flickr_username handling
  # TODO: add paging options
  store_and_return(_get_response("get_persons_teammates?id=#{username}").people)
end

#more ⇒ Object

Exposes paging from the last connection.



131
132
133
134
 
# File 'lib/r43.rb', line 131

def more()
  @response.more()
  return_by_value(@return_reference)
end

#search_cities(query) ⇒ Object

Implements the search_cities method of the Cities API

require 'r43'
connection = R43::Connection.new(<api_key>)
cities = connection.search_cities(<query>)



469
470
471
 
# File 'lib/r43.rb', line 469

def search_cities(query)
  store_and_return(_get_response("search_cities?q=#{query}").cities)
end

#search_goals(string, optional = {}) ⇒ Object

Implements the search_goals method from the Goals API and returns an array of Goal objects

require 'r43'
connection = R43::Connection.new(<api_key>)
goals = connection.search_goals(<query string>[,
                             {["offset" => <offset>], 
                              ["max" => <max>]}])



226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/r43.rb', line 226

def search_goals(string, optional={})
  string.gsub!(/\s/, "+") 
  if optional["offset"] then
    string += "&offset=#{optional["offset"]}"
  end
  if optional["max"] then
    string += "&max=#{optional["max"]}"
  end
  
  store_and_return(_get_response("search_goals?q=#{string}").goals)
end

#search_people(query, options = {}) ⇒ Object

Implements the search_people method from the People API and returns an array of Person objects. Response will be set on Connection and this is a paged collection.

require 'r43'
connection = R43::Connection.new(<api_key>)
people = connection.search_people(<query>)
people += connection.more



296
297
298
299
 
# File 'lib/r43.rb', line 296

def search_people(query, options={})
  # TODO: add paging options
  store_and_return(_get_response("search_people?q=#{query}").people)
end

#search_people_by_email(query, options = {}) ⇒ Object

Implements the search_people_by_email method from the People API and returns an array of Person objects. Response will be set on Connection and this is a paged collection.

require 'r43'
connection = R43::Connection.new(<api_key>)
people = connection.search_people_by_email(<query>)
people += connection.more



311
312
313
314
 
# File 'lib/r43.rb', line 311

def search_people_by_email(query, options={})
  # TODO: add paging options
  store_and_return(_get_response("search_people_by_email?q=#{query}").people)
end