timestamp_api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e4fca3476b72032b4d7c6f60103a1786233dd37
-  data.tar.gz: b5cd56f6c58af100d6603a12daa2553849fa0735
+  metadata.gz: 6a870a3e355cac05312491e1f1de0868959a58cb
+  data.tar.gz: 030bdb7e4306a523c303f66121b003661b7ea38a
 SHA512:
-  metadata.gz: 45f343a6cf9ed1bdbd90bb88f486af98031687f4649f016128201388d6e9d9619bbe4e93e359872529b9cb84490fbe4e65bc9eb3e061d3429cbaccf16b35df98
-  data.tar.gz: 835fcd3aa22f5b502be689036d2cb040f35a91b19c05cfaabc74931a6ffc85b24adac530b59565b61ab69770562b83a713b3848590c84d3aaf9d3ecb3fe09ab8
+  metadata.gz: b84b0632fd788418b36bc86a1398326973cc64f9676a875579285e35345aa2523f4789ddc75d427fe34b74e08866f2c762e355556e2f17b35ea831fe1a8c165f
+  data.tar.gz: d63292c7170080dc6b3b72b6a5183db06fe0bbb986610d22a9bf11769a1adfbf6cb4ec7043c53d97060685389114c0ab6ddee2a8ec9ef6d1396f77b25cb68286

data/.gitignore

@@ -10,3 +10,4 @@
 /.ruby-version
 /.ruby-gemset
 /.rvmrc
+*.gem

data/README.md

@@ -1,10 +1,13 @@
 # Timestamp API
 
 [![Build Status](https://travis-ci.org/alpinelab/timestamp_api.svg?branch=master)](https://travis-ci.org/alpinelab/timestamp_api)
+[![Code Climate](https://codeclimate.com/github/alpinelab/timestamp_api/badges/gpa.svg)](https://codeclimate.com/github/alpinelab/timestamp_api)
+[![Test Coverage](https://codeclimate.com/github/alpinelab/timestamp_api/badges/coverage.svg)](https://codeclimate.com/github/alpinelab/timestamp_api/coverage)
+[![Gem Version](https://badge.fury.io/rb/timestamp_api.svg)](https://badge.fury.io/rb/timestamp_api)
+[![security](https://hakiri.io/github/alpinelab/timestamp_api/master.svg)](https://hakiri.io/github/alpinelab/timestamp_api/master)
+[![Dependency Status](https://gemnasium.com/alpinelab/timestamp_api.svg)](https://gemnasium.com/alpinelab/timestamp_api)
 
-This gem is a set of Ruby bindings for the [Timestamp](https://www.timestamphq.com) API.
-
-:warning: The API is not documented nor even officially supported by Timestamp.
+This gem is an unofficial set of Ruby bindings for the [Timestamp](https://www.timestamphq.com) API.
 
 ## Installation
 
@@ -24,7 +27,59 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Configure your Timestamp API key by setting environment variable `TIMESTAMP_API_KEY` or manually:
+```ruby
+TimestampAPi.api_key = "YOUR_TIMESTAMP_API_KEY"
+```
+
+List all projects:
+```ruby
+projects = TimestampAPI::Project.all
+projects.map(&:name) # => ["A project", "Another project", "One more project"]
+```
+
+Find a given project:
+```ruby
+project = TimestampAPI::Project.find(123456)
+project.client.name # => "My beloved customer"
+```
+
+### 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):
+```ruby
+TimestampAPI.request(:get, "/projects")        # Same as TimestampAPI::Project.all
+TimestampAPI.request(:get, "/projects/123456") # Same as TimestampAPI::Project.find(123456)
+```
+
+Response is provided as a [RecursiveOpenStruct](https://github.com/aetherknight/recursive-open-struct) (or as an `Array` of `RecursiveOpenStruct`), thus can be accessed by:
+```ruby
+project = TimestampAPI.request(:get, "/projects/123456")
+project.id          # => 123456
+project.name        # => "Awesome project"
+project.client.name # => "My beloved customer"
+```
+
+## 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#all
+* [x] Project#find
+
+### What's not implemented yet ?
+
+* [ ] _everything else_ :scream:
 
 ## Development
 

data/bin/console

@@ -11,4 +11,7 @@ require "timestamp_api"
 # Pry.start
 
 require "irb"
-IRB.start
+require "awesome_print"
+require "pry"
+
+Pry.start

data/lib/timestamp_api/errors.rb

@@ -0,0 +1,13 @@
+module TimestampAPI
+  class MissingAPIKey < StandardError
+    def message
+      "API key must be configured either via the `TIMESTAMP_API_KEY` environment variable or using `TimestampAPi.api_key = \"YOUR_TIMESTAMP_API_KEY\"`."
+    end
+  end
+
+  class InvalidServerResponse < StandardError
+    def message
+      "Server responded with invalid JSON. A possible cause is an invalid or revoked API key."
+    end
+  end
+end

data/lib/timestamp_api/project.rb

@@ -0,0 +1,11 @@
+module TimestampAPI
+  class Project
+    def self.all
+      TimestampAPI.request(:get, "/projects")
+    end
+
+    def self.find(id)
+      TimestampAPI.request(:get, "/projects/#{id}")
+    end
+  end
+end

data/lib/timestamp_api/version.rb

@@ -1,3 +1,3 @@
 module TimestampAPI
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/timestamp_api.rb

@@ -1,5 +1,41 @@
+require "rest-client"
+require "recursive-open-struct"
+
 require "timestamp_api/version"
+require "timestamp_api/errors"
+require "timestamp_api/project"
 
 module TimestampAPI
-  # Your code goes here...
+  @api_endpoint = "https://api.ontimestamp.com/api"
+
+  class << self
+    attr_accessor :api_endpoint, :api_key
+  end
+
+  def self.request(method, url)
+    response = RestClient::Request.execute(request_options(method, url))
+    objectify(JSON.parse(response))
+  rescue JSON::ParserError
+    raise InvalidServerResponse
+  end
+
+  def self.request_options(method, url)
+    {
+      method:  method,
+      url:     api_endpoint + url,
+      headers: {
+        "X-API-Key" => api_key || ENV["TIMESTAMP_API_KEY"] || raise(MissingAPIKey),
+        :accept     => :json,
+        :user_agent => "TimestampAPI Ruby gem https://github.com/alpinelab/timestamp_api"
+      }
+    }
+  end
+
+  def self.objectify(json)
+    case json
+    when Array then json.map { |item| RecursiveOpenStruct.new(item, recurse_over_arrays: true) }
+    when Hash  then RecursiveOpenStruct.new(json, recurse_over_arrays: true)
+    else json
+    end
+  end
 end

data/timestamp_api.gemspec

@@ -19,7 +19,12 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_runtime_dependency "rest-client"
+  spec.add_runtime_dependency "recursive-open-struct"
+
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "awesome_print"
 end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: timestamp_api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Baudino
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-23 00:00:00.000000000 Z
+date: 2016-01-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: recursive-open-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +80,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 'Timestamp is "real-time project tracking for you and your clients" according
   to their website: https://www.timestamphq.com'
 email:
@@ -73,6 +129,8 @@ files:
 - bin/console
 - bin/setup
 - lib/timestamp_api.rb
+- lib/timestamp_api/errors.rb
+- lib/timestamp_api/project.rb
 - lib/timestamp_api/version.rb
 - timestamp_api.gemspec
 homepage: https://github.com/alpinelab/timestamp_api