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.
License
Copyright (c) 2013-2015 Tom Kane. Released under the MIT License. See LICENSE.txt for details.