Class: BasecampAPI
- Inherits:
-
Object
- Object
- BasecampAPI
- Defined in:
- lib/basecamp/basecamp.rb
Overview
A Ruby library for working with the Basecamp web-services API.
For more information about the Basecamp web-services API, visit:
http://developer.37signals.com/basecamp
NOTE: not all of Basecamp’s web-services are accessible via REST. This library provides access to RESTful services via ActiveResource. Services not yet upgraded to REST are accessed via the Basecamp class. Continue reading for more details.
Establishing a Connection
The first thing you need to do is establish a connection to Basecamp. This requires your Basecamp site address and your login credentials. Example:
Basecamp.establish_connection!('you.grouphub.com', 'username', 'password')
This is the same whether you’re accessing using the ActiveResource interface, or the legacy interface.
Using the REST interface via ActiveResource
The REST interface is accessed via ActiveResource, a popular Ruby library that implements object-relational mapping for REST web-services. For more information on working with ActiveResource, see:
* http://api.rubyonrails.org/files/activeresource/README.html
* http://api.rubyonrails.org/classes/ActiveResource/Base.html
Finding a Resource
Find a specific resource using the find
method. Attributes of the resource are available as instance methods on the resulting object. For example, to find a message with the ID of 8675309 and access its title attribute, you would do the following:
m = Basecamp::Message.find(8675309)
m.title # => 'Jenny'
To find all messages for a given project, use find(:all), passing the project_id as a parameter to find. Example:
= Basecamp::Message.find(:all, params => { :project_id => 1037 })
.size # => 25
Creating a Resource
Create a resource by making a new instance of that resource, setting its attributes, and saving it. If the resource requires a prefix to identify it (as is the case with resources that belong to a sub-resource, such as a project), it should be specified when instantiating the object. Examples:
m = Basecamp::Message.new(:project_id => 1037)
m.category_id = 7301
m.title = 'Message in a bottle'
m.body = 'Another lonely day, with no one here but me'
m.save # => true
c = Basecamp::Comment.new(:post_id => 25874)
c.body = 'Did you get those TPS reports?'
c.save # => true
You can also create a resource using the create
method, which will create and save it in one step. Example:
Basecamp::TodoItem.create(:todo_list_id => 3422, :contents => 'Do it')
Updating a Resource
To update a resource, first find it by its id, change its attributes, and save it. Example:
m = Basecamp::Message.find(8675309)
m.body = 'Changed'
m.save # => true
Deleting a Resource
To delete a resource, use the delete
method with the ID of the resource you want to delete. Example:
Basecamp::Message.delete(1037)
Attaching Files to a Resource
If the resource accepts file attachments, the attachments
parameter should be an array of Basecamp::Attachment objects. Example:
a1 = Basecamp::Attachment.create('primary', File.read('primary.doc'))
a2 = Basecamp::Attachment.create('another', File.read('another.doc'))
m = Basecamp::Message.new(:project_id => 1037)
...
m. = [a1, a2]
m.save # => true
Using the non-REST inteface
The non-REST interface is accessed via instance methods on the Basecamp class. Ensure you’ve established a connection, then create a new Basecamp instance and call methods on it. Object attributes are accessible as methods. Example:
session = Basecamp.new
person = session.person(93832) # => #<Record(person)..>
person.first_name # => "Jason"
Defined Under Namespace
Classes: Account, Attachment, Category, Comment, Company, Connection, Message, People, Project, Record, Resource, TimeEntry, TodoItem, TodoList, TodoListWithItems
Class Attribute Summary collapse
-
.password ⇒ Object
readonly
Returns the value of attribute password.
-
.site ⇒ Object
readonly
Returns the value of attribute site.
-
.use_ssl ⇒ Object
readonly
Returns the value of attribute use_ssl.
-
.user ⇒ Object
readonly
Returns the value of attribute user.
Instance Attribute Summary collapse
-
#use_xml ⇒ Object
Returns the value of attribute use_xml.
Class Method Summary collapse
Instance Method Summary collapse
-
#complete_milestone(id) ⇒ Object
Complete the milestone with the given id.
-
#create_milestone(project_id, data) ⇒ Object
Create a new milestone for the given project.
-
#create_milestones(project_id, milestones) ⇒ Object
As #create_milestone, but can create multiple milestones in a single request.
-
#delete_milestone(id) ⇒ Object
Destroys the milestone with the given id.
-
#initialize ⇒ BasecampAPI
constructor
A new instance of BasecampAPI.
-
#milestones(project_id, find = 'all') ⇒ Object
Returns a list of all milestones for the given project, optionally filtered by whether they are completed, late, or upcoming.
-
#people(company_id, project_id = nil) ⇒ Object
Return an array of the people in the given company.
-
#person(id) ⇒ Object
Return information about the person with the given id.
-
#uncomplete_milestone(id) ⇒ Object
Uncomplete the milestone with the given id.
-
#update_milestone(id, data, move = false, move_off_weekends = false) ⇒ Object
Updates an existing milestone.
Constructor Details
#initialize ⇒ BasecampAPI
Returns a new instance of BasecampAPI.
483 484 485 |
# File 'lib/basecamp/basecamp.rb', line 483 def initialize @use_xml = false end |
Class Attribute Details
.password ⇒ Object (readonly)
Returns the value of attribute password.
463 464 465 |
# File 'lib/basecamp/basecamp.rb', line 463 def password @password end |
.site ⇒ Object (readonly)
Returns the value of attribute site.
463 464 465 |
# File 'lib/basecamp/basecamp.rb', line 463 def site @site end |
.use_ssl ⇒ Object (readonly)
Returns the value of attribute use_ssl.
463 464 465 |
# File 'lib/basecamp/basecamp.rb', line 463 def use_ssl @use_ssl end |
.user ⇒ Object (readonly)
Returns the value of attribute user.
463 464 465 |
# File 'lib/basecamp/basecamp.rb', line 463 def user @user end |
Instance Attribute Details
#use_xml ⇒ Object
Returns the value of attribute use_xml.
460 461 462 |
# File 'lib/basecamp/basecamp.rb', line 460 def use_xml @use_xml end |
Class Method Details
.connection ⇒ Object
478 479 480 |
# File 'lib/basecamp/basecamp.rb', line 478 def connection @connection || raise('No connection established') end |
.establish_connection!(site, user, password, use_ssl = false) ⇒ Object
465 466 467 468 469 470 471 472 473 474 475 476 |
# File 'lib/basecamp/basecamp.rb', line 465 def establish_connection!(site, user, password, use_ssl = false) @site = site @user = user @password = password @use_ssl = use_ssl Resource.user = user Resource.password = password Resource.site = (use_ssl ? "https" : "http") + "://" + site @connection = Connection.new(self) end |
Instance Method Details
#complete_milestone(id) ⇒ Object
Complete the milestone with the given id
541 542 543 |
# File 'lib/basecamp/basecamp.rb', line 541 def complete_milestone(id) record "/milestones/complete/#{id}" end |
#create_milestone(project_id, data) ⇒ Object
Create a new milestone for the given project. data
must be hash of the values to set, including title
, deadline
, responsible_party
, and notify
.
517 518 519 |
# File 'lib/basecamp/basecamp.rb', line 517 def create_milestone(project_id, data) create_milestones(project_id, [data]).first end |
#create_milestones(project_id, milestones) ⇒ Object
As #create_milestone, but can create multiple milestones in a single request. The milestones
parameter must be an array of milestone values as described in #create_milestone.
524 525 526 |
# File 'lib/basecamp/basecamp.rb', line 524 def create_milestones(project_id, milestones) records "milestone", "/projects/#{project_id}/milestones/create", :milestone => milestones end |
#delete_milestone(id) ⇒ Object
Destroys the milestone with the given id.
536 537 538 |
# File 'lib/basecamp/basecamp.rb', line 536 def delete_milestone(id) record "/milestones/delete/#{id}" end |
#milestones(project_id, find = 'all') ⇒ Object
Returns a list of all milestones for the given project, optionally filtered by whether they are completed, late, or upcoming.
510 511 512 |
# File 'lib/basecamp/basecamp.rb', line 510 def milestones(project_id, find = 'all') records "milestone", "/projects/#{project_id}/milestones/list", :find => find end |
#people(company_id, project_id = nil) ⇒ Object
Return an array of the people in the given company. If the project-id is given, only people who have access to the given project will be returned.
493 494 495 496 497 |
# File 'lib/basecamp/basecamp.rb', line 493 def people(company_id, project_id=nil) url = project_id ? "/projects/#{project_id}" : "" url << "/contacts/people/#{company_id}" records "person", url end |
#person(id) ⇒ Object
Return information about the person with the given id
500 501 502 |
# File 'lib/basecamp/basecamp.rb', line 500 def person(id) record "/contacts/person/#{id}" end |
#uncomplete_milestone(id) ⇒ Object
Uncomplete the milestone with the given id
546 547 548 |
# File 'lib/basecamp/basecamp.rb', line 546 def uncomplete_milestone(id) record "/milestones/uncomplete/#{id}" end |
#update_milestone(id, data, move = false, move_off_weekends = false) ⇒ Object
Updates an existing milestone.
529 530 531 532 533 |
# File 'lib/basecamp/basecamp.rb', line 529 def update_milestone(id, data, move = false, move_off_weekends = false) record "/milestones/update/#{id}", :milestone => data, :move_upcoming_milestones => move, :move_upcoming_milestones_off_weekends => move_off_weekends end |