Timestamp API
This gem is an unofficial set of Ruby bindings for the Timestamp API.
Installation
Add this line to your application's Gemfile:
gem "timestamp_api"
And then execute:
$ bundle
Or install it yourself as:
$ gem install timestamp_api
Usage
Configure your Timestamp API key by setting environment variable TIMESTAMP_API_KEY
or manually:
TimestampAPi.api_key = "YOUR_TIMESTAMP_API_KEY"
Projects
List all projects:
TimestampAPI::Project.all
Find a given project:
project = TimestampAPI::Project.find(123)
project.name # => "My awesome project"
Clients
List all clients:
TimestampAPI::Client.all
Find a given client:
client = TimestampAPI::Client.find(123)
client.name # => "My beloved customer"
Find the client of a project
project = TimestampAPI::Project.find(123)
project.client.name # => "My beloved customer"
Models
The objects are represented by model classes (that inherits from TimestampAPI::Model
):
project = TimestampAPI::Project.find(123456)
project.class # => TimestampAPI::Project
project.is_a? TimestampAPI::Model # => true
Collections of objects are represented by TimestampAPI::Collection
that inherits from Array
(and implement the chainable .where(conditions)
filter method described above). It means any Array
method works on TimestampAPI::Collection
:
projects = TimestampAPI::Project.all
projects.class # => TimestampAPI::Collection
projects.map(&:name) # => ["A project", "Another project", "One more project"]
Filtering
You can filter any object collection using the handy .where()
syntax:
projects = TimestampAPI::Project.all
projects.where(is_public: true) # => returns all public projects
projects.where(is_public: true, is_billable: true) # => returns all projects that are both public and billable
projects.where(is_public: true).where(is_billable: true) # => same as above: `where` is chainable \o/
:information_source: This does not filter objects before the network call (like ActiveRecord does), it's only a more elegant way of calling Array#select
on the Collection
Low level API calls
The above methods are simple wrappers around the generic low-level-ish API request method TimestampAPI.request
that take a HTTP method
(verb) and a path
(to be appended to preconfigured API endpoint URL):
TimestampAPI.request(:get, "/projects") # Same as TimestampAPI::Project.all
TimestampAPI.request(:get, "/projects/123456") # Same as TimestampAPI::Project.find(123456)
To output all network requests done, you can set verbosity on:
TimestampAPI.verbose = true
Reverse engineering
As the API is not documented nor even officially supported by Timestamp, we're trying to reverse-engineer it.
:warning: This means that Timestamp can introduce breaking changes within their API without prior notice at any time (and thus break this gem).
It also means that if you're willing to hack into it with us, you're very welcome :+1:
While logged in, the Timestamp API data can be explored from your favourite browser (with a JSON viewer addon, if needed) here: https://api.ontimestamp.com/api
There's also a bin/console
executable provided with this gem, if you want a REPL to hack around.
What's implemented already ?
- [x]
Project
model - [x]
Client
model - [x]
Task
model - [x]
belongs_to
relationships
What's not implemented yet ?
- [ ] all other models :scream:
- [ ]
has_many
relationships - [ ] document and integrate Inch-CI
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
to create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
- Fork it ( https://github.com/alpinelab/timestamp_api/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
License
This code is distributed by Alpine Lab under the terms of the MIT license.
See LICENCE.md