Timing and Scoring JSON API

Use this gem to consume the T&S JSON API provided for live & summary race data.

Installation

Add the gem to your Gemfile

gem 'ts_json_api'

Run the following rails generator to setup the gem

> rails g ts_json_api:install

This generator creates an initializer that you will need to configure for your access token to use the API.

Configuration

This gem provides several configuration options exposed in an ts_json_api.rb initializer that is created for you when you run the included generator.

TsJsonApi::Configure.setup do |config|
    config.username = ""
    config.password = ""
    config.logging_enabled = true
    config.server_url = ""
    config.timestamped_logs = false

    config.api_version = 2
    config.api_version = ->(url) do
      if url =~ /livepoints/
        'include_wins'
      else
        2
      end
    end
end

The username, password, and server_url fields are all requried to specify which service to connect to. The api_version field allows you to specify a particular version or contract you have in place with the T&S team when authenticating with the service.

You can specify a lambda for the api_version setting, or any instance that responds to #call and accepts one argument of the URL being requested, to dynamically return the version for the request.

You can disable logging by setting logging_enabled = false. Logging will log the raw response from the T&S service into the Rails tmp/ts_json_api/ directory for you to review.

If you wish to keep a log file for every transaction with the API, you will want to enabled timestamped_logs. This feature will keep a unique file instead of overwriting the previous response from the API every time.

If you use this feature, we highly encourage you to run the included rake task:

> bundle exec rake ts_json_api:remove_old_log_files

Usage

This gem exposes several methods that map directly to API calls from the T&S team.

Syntax

You are offered two ways to initiate calls. The first is shorthand for the second.

TsJsonApi.weekend 4080
TsJsonApi::Requestor.weekend 4080

Examples

Example calls follow:

# Drivers
TsJsonApi.get_drivers(year, series_id)
TsJsonApi.driver_summary(race_season, series_id, driver_id=nil)

# Live Feed
TsJsonApi.live_feed
TsJsonApi.live_flag
TsJsonApi.live_points

# Points
TsJsonApi.points_per_race(race_season, series_id, race_id=nil)

# Races
TsJsonApi.get_race(race_id)
TsJsonApi.races_in_season(race_season, series_id, driver_id=nil)

# Schedule
TsJsonApi.schedule_for_race(race_id)
TsJsonApi.schedule_for_season(race_season, series_id)

# Series
TsJsonApi.series

# Tracks
TsJsonApi.get_track(track_id, series_id=nil)

# Weekend
TsJsonApi.weekend(race_id)

Exceptions

The gem also provides the following exceptions you should watch out for:

begin
    TsJsonApi.live_data

rescue TsJsonApi::ApiLimitExceededException
    puts "rate limit exceeded"

rescue TsJsonApi::ResourceNotFound
    puts "requested URL not found, shouldn't ever happen"

rescue TsJsonApi::ServerBrokeConnection
    puts "connection to server was broken"

rescue TsJsonApi::AccessTokenRefused
    puts "access token was refused for this server: #{TsJsonApi::Configure.server_url}"

rescue TsJsonApi::Exception => e
    puts "some exception bubbled up from RestClient: #{e}, or a catch-all for all TsJsonApi exceptions"

Logging

There are settings mentioned above to enable logging so that the gem will log files automatically when a request is made. However, there is also a simple API to read and utilize the information stored in the log files. For example, to get the contents of the response from the most recent TsJsonApi.series call that was made:

f = TsJsonApi::Logging::File.new relative_path "series.log", readonly: true
f.contents[:content]
# => Hash/Array, actual JSON response made earlier
f.contents[:time]
# => Time object
f.contents[:url]
# => "http://server.url/api/series"

If you have the absolute path to the file:

f = TsJsonApi::Logging::File.new path: my_path, readonly: true

Testing

The test suite is written in rpsec, so just run rake spec to see the status of the tests.