NB. This gem is missing a lot of the Basecamp endpoints. Please feel free to contribute!
Fully-fledged Ruby API wrapper for Basecamp Next
___________________ ____ ___
\______ \_ ___ \\ \/ /
| | _/ \ \/ \ /
| | \ \____/ \
|______ /\______ /___/\ \
\/ \/ \_/
$ gem install bcx
Or if you are using Bundler, add
gem 'bcx'
to your Gemfile
and run
$ bundle install
Configure Bcx for your Basecamp account
Bcx.configure do |config|
config.account = '1234567890'
end
Before connecting to the Basecamp API you can optionally use this client to obtain a list of a user’s available accounts and products. They may be a mix of Basecamp Next, Basecamp Classic, Campfire & other products.
From 37signal’s API docs:
This endpoint should be first request made after you’ve obtained a user’s authorization token via OAuth. You can pick which account to use for a given product, and then base where to make requests to from the chosen account’s href field.
launchpad = Bcx::Launchpad::OAuth.new(client_id: '1234567890', client_secret: '831994c4170', access_token: 'b02ff9345c3')
authorization = launchpad.authorization!
authorization.identity.name
# => "Joe Bloggs"
authorization.accounts
# => [...]
See these docs for more details.
You can connect to the Basecamp API using the Bcx client. The client provides authentication over HTTP or OAuth.
client = Bcx::Client::HTTP.new(login: 'username', password: 'secret')
client = Bcx::Client::OAuth.new(client_id: '1234567890', client_secret: '831994c4170', access_token: 'b02ff9345c3')
You can get a client_id
and client_secret
from https://integrate.37signals.com/
You can also pass an :account
option to the OAuth client (allowing multiple clients in your app).
client = Bcx::Client::OAuth.new(account: 99999999, ...)
The following resources are fully implemented and tested.
It’s important to understand the use of bang methods when using Bcx. Each resource can be called with or without a !
.
Without the bang you can chain and build endpoint calls:
client.projects(123).todolists
# => #<Bcx::Resources::Todolist ...>
client.projects(123).todolists.url
# => "projects/123/todolists"
With the bang you can hit the API endpoint over the network and fetch data:
client.projects(123).todolists!
# => [#<Hashie::Mash id=456 ...>, #<Hashie::Mash id=789 ...>]
If the response whilst fetching a resource is a 4xx or 5xx, Bcx will raise a Bcx::ResponseError
exception.
client.projects.create!(name: '')
# => Bcx::ResponseError: 422 POST https://basecamp.com/2274488/api/v1/projects.json | Errors: name can't be blank
You can rescue this exception to grab the status, method, URL and errors individually.
begin
client.projects.create!(name: '')
rescue Bcx::ResponseError => response
response.method # => "POST"
response.status # => 422
response.url # => "https://basecamp.com/2274488/api/v1/projects.json"
response.errors # => ["name can't be blank"]
end
See the full annotated source code.
The docs are generated using Docco. To generate the docs, run:
$ npm install -g docco
$ rake docs:generate
The endpoints listed under Resources above are implemented and tested.
All other endpoints still need implementing, see the official Basecamp Next API docs for details on what to implement.
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)