grepdata_client 0.0.2 → 0.0.3

data/README.md

@@ -1,36 +1,75 @@
-# GrepdataClient
+GrepdataClient
 
-Official Ruby client for Grepdata API
+Official Ruby client for Grepdata API.  More info on GrepData APIs can be found 
+in the [GrepData docs](www.grepdata.com/docs).
 
 ## Installation
 
     gem install grepdata_client
+    gem install typhoeus
 
 or if you use a Gemfile:
 
     gem 'grepdata_client'
-    
+    gem 'typhoeus'
+
 ## Publishing Events
 
+The track call allows you to send data into the system, usually from client devices. 
+Setup the client with your public token (token) and the endpoint (default_endpoint), 
+generally either 'prod' or 'qa', to send data. These can be found in 
+[settings](www.grepdata.com/#/settings/account) and 
+[endpoints](www.grepdata.com/#/settings/endpoints) respectively. Each track call 
+requires a first parameter of event name and a second JSON object with any related 
+dimensions you would like to track along with this event. For more info see 
+[docs for sending data](www.grepdata.com/docs#sending).
+
+###Example
+
     require 'rubygems'
     require 'grepdata_client'
 
-    client = GrepdataClient::Client.new(token: "054a9c9ade7dcf325a3aab542ebd73b5", default_endpoint: 'demonstration')
-    client.track 'play', data: { age: 18 }
+    client = GrepdataClient::Client.new(:token => "abcdefghijklmnopqrstuvwxyz123456", :default_endpoint => 'prod')
+    client.track 'play', data: { :age => 18 }
 
 ## Querying Data 
 
+Querying data using the GrepData API is almost as simple as sending it. This time
+the client is configured using the private key (api_key) for your account which can 
+be found in [settings](www.grepdata.com/#/settings/account). 
+
+
+### Data Query
+
+Each data request requires a params object including the following fields:
++ **datamart** (string): the name of the datamart to query (endpoint name for timeseries data)
++ **dimensions** (array): all dimensions to query, be sure to include any dimensions being filtered
++ **filters** (JSON): an object containing any filters to apply to the selected dimensions, key is dimension name, value is array of valid options
++ **metrics** (array): all metrics columns you want aggregated and returned
++ **time_interval** (string): the time granularity to breakout, options are h => hour, d => day, m => month
++ **start_date** (string): the inclusive start of the query in format yyyymmddhh00
++ **end_date** (string): the inclusive end of the query in format yyyymmddhh00
+
+The `client.query` call will return a query object which can be executed with the method `get_result` or printed as 
+a the complete API url that will be executed with `get_url`.
+
+###Example
+From the user_info datamart
+Select the hour, country and the total count of events 
+Where the country is either US, UK or CA and the event was between 2013/06/11 08:00 and 2013/06/11 09:00
+Grouped by hour and country
+
     require 'rubygems'
     require 'grepdata_client'
-
-    client = GrepdataClient::Client.new(:api_key => "0ac15f3688987af763c67412066e3378")
+        
+    client = GrepdataClient::Client.new(:api_key => "abcdefghijklmnopqrstuvwxyz123456")
     
     #Query
     params =  { 
       :datamart => "user_info",
       :dimensions => %w(country),
       :metrics => %w(Count),
-      :filters => { :country => %w(US) },
+      :filters => { :country => %w(US UK CA) },
       :time_interval => "h",
       :start_date => "201306110800",
       :end_date => "201306110900"
@@ -38,6 +77,30 @@ or if you use a Gemfile:
     req = client.query params
     puts req.get_result
 
+Funneling queries can also be issued from this client. Similar to querying above, the 
+client is configured with the api_key and fired with a set of query parameters:
++ **datamart** (string): the name of the datamart to query (endpoint name for timeseries data)
++ **funnel_dimension** (string): the dimension used to identify individual steps in this funnel, usually 'event'
++ **dimensions** (array): all dimensions included in the query, be sure to include any dimensions being filtered and funnel_dimension
++ **filters** (JSON): an object containing any filters to apply to the selected dimensions, key is dimension name, value is array of valid options
++ **metrics** (array): all metrics columns you want aggregated and returned
++ **time_interval** (string): the time granularity upon which to query, should align with start and end date boundaries, options are h => hour, d => day, m => month
++ **start_date** (string): the inclusive start of the query in format yyyymmddhh00
++ **end_date** (string): the inclusive end of the query in format yyyymmddhh00 
++ **steps** (array of JSON): an ordered array containing JSON objects for each step with a friendly display name (name) and the actual dimension value in the data (value) 
++ **only_totals** (boolean): a flag to indicate whether to collapse all data from the given timerange into a single total (true) or leave it broken out by time_interval (false)
+
+###Example
+From the demonstration datamart
+Select the daily counts of play, pause, seek and stop events 
+Where the country is US and the events occurred between 2013/06/12 and 2013/06/19
+Broken out by day and country
+
+    require 'rubygems'
+    require 'grepdata_client'
+        
+    client = GrepdataClient::Client.new(:api_key => "abcdefghijklmnopqrstuvwxyz123456")
+
     #Funneling
     params = { 
       :datamart => 'demonstration',
@@ -51,67 +114,89 @@ or if you use a Gemfile:
         { :name => "step1: play", :value => "play" },
         { :name => "step2: pause", :value => "pause" },
         { :name => "step3: seek", :value => "seek" },
-        { :name => "step2: stop", :value => "stop" }
+        { :name => "step4: stop", :value => "stop" }
       ],
       :filters => { :country => %w(US) },
       :only_totals => false
     }
     req = client.funneling params
     puts req.get_result
+  
+## Dimensions Query
+
+Before querying for data, it may be useful to retreive a list of all available dimensions sent to a 
+given endpoint.  This can be acheived with the dimensions query, simply by supplying the api_key
+and the datamart name.
 
-## Generating access key
+###Example
+Show all dimensions that have been included with events sent to the demonstration endpoint
 
     require 'rubygems'
     require 'grepdata_client'
-
-    client = GrepdataClient::Client.new(:api_key => "0ac15f3688987af763c67412066e3378")
     
-    params =  { 
-      :datamart => "user_info",
-      :dimensions => %w(country),
-      :metrics => %w(Count),
-      :filters => { :country => %w(US) },
-      :time_interval => "h",
-      :start_date => "201306110800",
-      :end_date => "201306110900"
-    }
+    client = GrepdataClient::Client.new(:api_key => "abcdefghijklmnopqrstuvwxyz123456")
     
-    access_key = client.generate_access_key api_key, 
-      params: params, 
-      restricted: ['dimensions', 'filters.country'],
-      expiration: '201306220100'
-      
-    puts access_key
+    params = { :endpoint => 'demonstration' }
+    req = client.dimensions params
+    
+    puts req.get_result
+    
+
+##Restricted Queries
+While the above method for querying is relatively straight forward, it requires the use of your 
+secret api_key, a method which is only suitable for internal or server-side calls since anyone
+with this key can access all your account's data. However, it is possible to safely expose a 
+controlled subset of the data externally without exposing your secret key.  
+
+We previously discussed the `client.query` call that generates a normal query, but there is also 
+a second method `client.get_safe_url` which will return a simple url using your public token
+and a special 'signature' access token in place of the api_key. This url will not have your api_key 
+included and so it can safely be passed to a client and called from the client side. 
 
-## Querying with access key
+The generated signature acts like a checksum, restricting the resulting query to execute only with 
+the restricted parameters you specify when calling `client.get_safe_url` on the server side. By 
+default, with no options set, the generated url will be signed such that no modifications are
+possible. However, looser restrictions can be applied by passing a `restricted` array to the method.
+This array of strings should contain all fields which the client should _not_ be allowed to change. 
+All other fields will be modifiable by the client (with the exception of datamart, which can never 
+be changed). 
+
+An optional `expiration` time is also available when generating the safe url generation to restrict 
+for how long the url will remain valid.
+
+###Example
+Generate a url that cannot be modified and a few which can be partially modified
 
     require 'rubygems'
     require 'grepdata_client'
-
-    client = GrepdataClient::Client.new(:token => "054a9c9ade7dcf325a3aab542ebd73b5")
     
-    #acquired via generate_access_key
-    access_key = {
-      :signature=>"0xBBKoaUe6RZSLM//6yqzbYelmI=", 
-      :restricted=>"dimensions,filters.country", 
-      :expiration=>"201306220100", 
-    }
+    #note that we need to include both the token and api_key. The token can either be in this client initialization or in the params
+    client = GrepdataClient::Client.new(:api_key => "abcdefghijklmnopqrstuvwxyz123456", :token => "abcdefghijklmnopqrstuvwxyz123456")
     
     params =  { 
       :datamart => "user_info",
-      :dimensions => %w(country),
+      :dimensions => %w(country gender),
       :metrics => %w(Count),
-      :filters => { :country => %w(US) },
+      :filters => { :country => %w(US UK), :gender => %w(M) },
       :time_interval => "h",
       :start_date => "201306110800",
       :end_date => "201306110900"
     }
-
-    req = client.query_with_token params, access_key
-    puts req.get_result
     
-    #get url of the request
-    puts req.get_url
+    #generate a fully restricted, immutable request that expires at 201312312300
+    fully_safe_url = client.get_safe_url(params, expiration:"201312312300")       
+    puts fully_safe_url
+
+    #generate a loosely restricted url that allows the client to modify only the dates and interval
+    restricted = %w(datamart dimensions metrics filters)
+    time_free_safe_url = client.get_safe_url(params, expiration:"201312312300", restricted:restricted)       
+    puts time_free_safe_url
+
+    #individual filters may be locked with dot notation without other filters being locked as well
+    #this will generate a query which allows the gender filters to be changed but not the country    
+    restricted = %w(datamart dimensions metrics filters.country)
+    time_and_gender_free_safe_url = client.get_safe_url(params, expiration:"201312312300", restricted:restricted)       
+    puts time_and_gender_free_safe_url
 
 ## Running Request in Parallel
 
@@ -121,8 +206,8 @@ or if you use a Gemfile:
     #set parallel to true
     client = GrepdataClient::Client.new(
       :default_endpoint => 'demonstration', 
-      :token => "054a9c9ade7dcf325a3aab542ebd73b5",
-      :api_key => "0ac15f3688987af763c67412066e3378",
+      :token => "abcdefghijklmnopqrstuvwxyz123456",
+      :api_key => "abcdefghijklmnopqrstuvwxyz123456",
       :parallel => true)
     
     # query or publish data.  Requests will be queued up
@@ -140,8 +225,8 @@ We use Typhoeus to handle parallel requests.  You can also pass in your own hydr
     hydra = ::Typhoeus::Hydra.new
     client = GrepdataClient::Client.new(
       :default_endpoint => 'demonstration', 
-      :token => "054a9c9ade7dcf325a3aab542ebd73b5",
-      :api_key => "0ac15f3688987af763c67412066e3378",
+      :token => "abcdefghijklmnopqrstuvwxyz123456",
+      :api_key => "abcdefghijklmnopqrstuvwxyz123456",
       :parallel => true,
       :parallel_manager => hydra)
       

data/lib/grepdata_client.rb

@@ -2,7 +2,7 @@ require "typhoeus"
 require 'base64'
 require 'openssl'
 require 'json'
-require 'Date'
+require 'date'
 
 require "grepdata_client/version"
 require "grepdata_client/query"
@@ -102,6 +102,52 @@ module GrepdataClient
       request(__method__, params: params)
     end
     
+    def get_safe_url(params, options={})
+      params[:token] = params[:token] || @token
+      api_key = params[:api_key] || @api_key
+      params.delete(:api_key)
+      params[:filters] = params[:filters] || {}
+      expiration = options[:expiration] || Utils.default_expiration
+      
+      restricted = options[:restricted] || ["datamart", "dimensions", "metrics", "filters", "time_interval", "start_date", "end_date"]
+   
+      access_key = generate_access_key(api_key, params:params, restricted:restricted, expiration:expiration)
+      
+      Utils.preprocess_dates params, [:start_date, :end_date]
+      Utils.preprocess_dates access_key, [:expiration]      
+
+      Utils.check_attributes "Request", 
+        params: params,
+        required: {
+          token: String, 
+          datamart: String,
+          dimensions: Array,
+          metrics: Array,
+          filters: Hash,
+          time_interval: String,
+          start_date: String,
+          end_date: String
+        }
+      
+      Utils.check_attributes "access_key",
+        params: access_key,
+        required: { 
+          signature: String, 
+          restricted: String,
+          expiration: String
+        }
+        
+      params[:signature] = access_key[:signature]
+      params[:restricted] = access_key[:restricted]
+      params[:expiration] = access_key[:expiration]
+      
+      query = GrepdataClient::DataRequest.new "fetch", 
+                url: @api_url, 
+                params: params
+
+      query.get_url
+    end
+    
     def funneling(params)
       params[:api_key] = params[:api_key] || @api_key
       params[:filters] = params[:filters] || {}
@@ -140,46 +186,6 @@ module GrepdataClient
       request(__method__, params: params)
     end
     
-    def query_with_token(params, access_key)
-      params[:token] = params[:token] || @token
-      params[:filters] = params[:filters] || {}
-      
-      Utils.preprocess_dates params, [:start_date, :end_date]
-      Utils.preprocess_dates access_key, [:expiration]
-      
-      Utils.check_attributes "Request", 
-        params: params,
-        required: {
-          token: String, 
-          datamart: String,
-          dimensions: Array,
-          metrics: Array,
-          filters: Hash,
-          time_interval: String,
-          start_date: String,
-          end_date: String
-        }
-      
-      Utils.check_attributes "access_key",
-        params: access_key,
-        required: { 
-          signature: String, 
-          restricted: String,
-          expiration: String
-        }
-    
-      headers = {}  
-      if @send_with_headers
-        headers = access_key
-      else
-        params[:signature] = access_key[:signature]
-        params[:restricted] = access_key[:restricted]
-        params[:expiration] = access_key[:expiration]
-      end
-      
-      request('fetch', params: params, headers: headers)
-    end
-    
     def run_requests
       @parallel_manager.run if @parallel_manager
     end
@@ -240,3 +246,4 @@ module GrepdataClient
     end
   end
 end
+

data/lib/grepdata_client/query.rb

@@ -21,4 +21,4 @@ module GrepdataClient
       return @request.url
     end
   end
-end
+end

data/lib/grepdata_client/version.rb

@@ -1,3 +1,3 @@
 module GrepdataClient
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grepdata_client
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-21 00:00:00.000000000 Z
+date: 2013-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus