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. r43 supports multiple servers in the 43things family and the use of a web proxy.

require 'r43'
connection = R43::Connection.new(<api_key> [, <url> [, 
    <proxy_address> [, <proxy_port> [, <proxy_user> [,
    <proxy_password]]]]])

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key, url = "www.43things.com", proxy_addr = nil, proxy_port = nil, proxy_user = nil, proxy_pass = nil) ⇒ Connection

Returns a new instance of Connection.



266
267
268
269
270
 
# File 'lib/r43.rb', line 266

def initialize(key, url="www.43things.com", proxy_addr=nil, proxy_port=nil, 
               proxy_user=nil, proxy_pass=nil)
  @service = R43::Service.new(key, url, proxy_addr, proxy_port,
                              proxy_user, proxy_pass)
end

Instance Attribute Details

#response ⇒ Object (readonly)

Returns the value of attribute response.



264
265
266
 
# File 'lib/r43.rb', line 264

def response
  @response
end

#service ⇒ Object (readonly)

Returns the value of attribute service.



264
265
266
 
# File 'lib/r43.rb', line 264

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 ++



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

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



336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/r43.rb', line 336

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



748
749
750
 
# File 'lib/r43.rb', line 748

def get_city(id)
  store_and_return(_get_response("get_city?id=#{id.to_i}").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>)



760
761
762
763
764
765
 
# File 'lib/r43.rb', line 760

def get_citys_people(id, optional={})
  @string, @optional = "id=#{id.to_i}", optional
  _handle_optional

  store_and_return(_get_response("get_citys_people?#{@string}").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>)



669
670
671
 
# File 'lib/r43.rb', line 669

def get_entry(id)
  store_and_return(_get_response("get_entry?id=#{id.to_i}").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)



374
375
376
 
# File 'lib/r43.rb', line 374

def get_goal_by_id(id)
  store_and_return(_get_response("get_goal_by_id?id=#{id.to_i}").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>)



387
388
389
390
 
# File 'lib/r43.rb', line 387

def get_goal_by_name(name)
  name = _clean_string(name)
  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>]}])



453
454
455
456
457
 
# File 'lib/r43.rb', line 453

def get_goals_entries(id, optional={})
  @string, @optional = "id=#{id.to_i}", optional
  _handle_optional
  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>]}])



437
438
439
440
441
 
# File 'lib/r43.rb', line 437

def get_goals_people(id, optional={})
  @string, @optional = "id=#{id.to_i}", optional
  _handle_optional
  store_and_return(_get_response("get_goals_people?#{@string}").people)
end

#get_goals_similarities(id, optional = {}) ⇒ 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>)



403
404
405
406
407
 
# File 'lib/r43.rb', line 403

def get_goals_similarities(id, optional={})
  @string, @optional = "id=#{id.to_i}", optional
  _handle_optional
  store_and_return(_get_response("get_goals_similarities?#{@string}").goals)
end

#get_person(username, 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>])



507
508
509
510
511
512
513
514
 
# File 'lib/r43.rb', line 507

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

#get_persons_completed_things(username, optional = {}) ⇒ 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



525
526
527
528
529
530
 
# File 'lib/r43.rb', line 525

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

#get_persons_entries(username, optional = {}) ⇒ 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.

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



542
543
544
545
546
547
 
# File 'lib/r43.rb', line 542

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

#get_persons_neighbors(username, optional = {}) ⇒ 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



598
599
600
601
602
603
 
# File 'lib/r43.rb', line 598

def get_persons_neighbors(username, optional={})
  # TODO: add flickr_username handling
  @string, @optional = "id=#{username}", optional
  _handle_optional
  store_and_return(_get_response("get_persons_neighbors?#{@string}").people)
end

#get_persons_progress_on_goal(username, goal_id, optional = {}) ⇒ 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



560
561
562
563
564
565
 
# File 'lib/r43.rb', line 560

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

#get_persons_tag_cloud(username, optional = {}) ⇒ 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])



653
654
655
656
657
658
 
# File 'lib/r43.rb', line 653

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

#get_persons_tags(username, optional = {}) ⇒ 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])



615
616
617
618
619
620
 
# File 'lib/r43.rb', line 615

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

#get_persons_teammates(username, optional = {}) ⇒ 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



579
580
581
582
583
584
 
# File 'lib/r43.rb', line 579

def get_persons_teammates(username, optional={})
  # TODO: add flickr_username handling
  @string, @optional = "id=#{username}", optional
  _handle_optional
  store_and_return(_get_response("get_persons_teammates?#{@string}").people)
end

#get_tags_goals(tag, optional = {}) ⇒ Object

Implements the get_tags_goals method from the Tag API. It returns an array of tags.

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



702
703
704
705
706
707
 
# File 'lib/r43.rb', line 702

def get_tags_goals(tag, optional={})
  query = _clean_string(tag)
  @string, @optional = "id=#{query}", optional
  _handle_optional
  store_and_return(_get_response("get_tags_goals?#{@string}").goals)
end

#get_tags_similarities(tag, optional = {}) ⇒ Object

Implements the get_tags_similarities method from the Tag API. It returns an array of tags.

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



718
719
720
721
722
723
 
# File 'lib/r43.rb', line 718

def get_tags_similarities(tag, optional={})
  query = _clean_string(tag)
  @string, @optional = "id=#{query}", optional
  _handle_optional
  store_and_return(_get_response("get_tags_similarities?#{@string}").tags)
end

#get_teams_progress(team_id) ⇒ Object

Implements the get_teams_progress from the Team API it returns an array of entries. The array may be paginated.

require 'r43'
connection = R43::Connection(<api_key>)
entries = connection.get_teams_progress(<team_id>)

The get_teams_progress API method also returns an array of Person objects. This array can be accessed through the R43::Connection#people method

people = connection.people



638
639
640
641
 
# File 'lib/r43.rb', line 638

def get_teams_progress(team_id)
  store_and_return(
         _get_response("get_teams_progress?id=#{team_id}").entries)
end

#more ⇒ Object

Exposes paging from the last connection.

require 'r43'
connection = R43::Connection(<api_key>)
people = connection.get_goals_people(<goal_id>)
people += connection.more



322
323
324
325
 
# File 'lib/r43.rb', line 322

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

#search_cities(query, optional = {}) ⇒ Object

Implements the search_cities method of the Cities API

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



733
734
735
736
737
738
 
# File 'lib/r43.rb', line 733

def search_cities(query, optional={})
  query = _clean_string(query)
  @string, @optional = "q=#{query}", optional
  _handle_optional
  store_and_return(_get_response("search_cities?q=#{query}").cities)
end

#search_goals(query, 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>]}])



420
421
422
423
424
425
 
# File 'lib/r43.rb', line 420

def search_goals(query, optional={})
  query = _clean_string(query)
  @string, @optional = "q=#{query}", optional
  _handle_optional
  store_and_return(_get_response("search_goals?#{@string}").goals)
end

#search_people(query, optional = {}) ⇒ 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> [,
                                      {[:offset => <offset>],
                                       [:max    => <max>]}])
people = connection.search_people(<query>)
people += connection.more



472
473
474
475
476
477
 
# File 'lib/r43.rb', line 472

def search_people(query, optional={})
  query = _clean_string(query)
  @string, @optional = "q=#{query}", optional
  _handle_optional
  store_and_return(_get_response("search_people?#{@string}").people)
end

#search_people_by_email(query, optional = {}) ⇒ 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



489
490
491
492
493
494
 
# File 'lib/r43.rb', line 489

def search_people_by_email(query, optional={})
  query = _clean_string(query)
  @string, @optional = "q=#{query}", optional
  _handle_optional
  store_and_return(_get_response("search_people_by_email?#{@string}").people)
end

#search_tags(query, optional = {}) ⇒ Object

Implements the search_tags method from the Tag API. It returns an array of tags.

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

Once constructed, a tag can be grown by repeated calls to the R43::Connection#more method.

tags += connection.more



686
687
688
689
690
691
 
# File 'lib/r43.rb', line 686

def search_tags(query, optional={})
  query = _clean_string(query)
  @string, @optional = "q=#{query}", optional
  _handle_optional
  store_and_return(_get_response("search_tags?#{@string}").tags)
end