Toggl API v8

Toggl is a time tracking tool.

togglv8 is a Ruby Wrapper for Toggl API v8. It is designed to mirror the Toggl API as closely as possible.

Note: Currently togglv8 only includes calls to Toggl API, not the Reports API

Installation

Add this line to your application's Gemfile:

gem 'togglv8'

And then execute:

$ bundle

Or install it yourself as:

$ gem install togglv8

Usage

This short example shows one way to create a time entry for the first workspace of the user identified by <API_TOKEN>:

require 'togglv8'

toggl_api    = TogglV8::API.new(<API_TOKEN>)
user         = toggl_api.me(all=true)
workspaces   = toggl_api.my_workspaces(user)
workspace_id = workspaces.first['id']
toggl_api.create_time_entry({
  'description' => "Workspace time entry",
  'wid' => workspace_id,
  'duration' => 1200,
  'start' => "2015-08-18T01:13:40.000Z",
  'created_with' => "My awesome Ruby application"
})

See specs for more examples.

Note: Requests are rate-limited. The togglv8 gem will handle a 429 response by pausing for 1 second and trying again, for up to 3 attempts. See Toggl API docs:

For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.

Documentation

Run rdoc to generate documentation. Open doc/index.html in your browser.

Also available on DocumentUp

Test Coverage

Open coverage/index.html to see test coverage.

As of 2015-12-10, coverage is "98.04% covered at 9.5 hits/line" according to SimpleCov.

Note: Coverage is 91.2% when Pro account features are not tested.

Acknowledgements

Thanks to Koen Van der Auwera for the Ruby Wrapper for Toggl API v6
Thanks to the Toggl team for exposing the API.

Contributing

Fork it ( https://github.com/kanet77/togglv8/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Pull Requests that include tests are much more likely to be accepted and merged quickly.