class TflApi::Client

This is the client class that allows direct access to the subclasses and to the TFL API. The class contains methods that perform GET and POST requests to the API.

Constants

VALID_PARAMS

Parameters that are permitted as options while initializing the client

VERB_MAP

HTTP verbs supported by the Client

Attributes

app_id[R]

Client accessors

app_key[R]

Client accessors

host[R]

Client accessors

log_level[R]

Client accessors

log_location[R]

Client accessors

logger[R]

Client accessors

Public Class Methods

new(args) click to toggle source

Initialize a Client object with TFL API credentials

@param args [Hash] Arguments to connect to TFL API

@option args [String] :app_id the application id generated by registering an app with TFL @option args [String] :app_key the application key generated by registering an app with TFL @option args [String] :host the API's host url - defaults to api.tfl.gov.uk

@return [TflApi::Client] a client object to the TFL API

@raise [ArgumentError] when required options are not provided.

# File lib/tfl_api_client/client.rb, line 62
def initialize(args)
  args.each do |key, value|
    if value && VALID_PARAMS.include?(key.to_s)
      instance_variable_set("@#{key.to_sym}", value)
    end
  end if args.is_a? Hash

  # Ensure the Application ID and Key is given
  raise ArgumentError, "Application ID (app_id) is required to interact with TFL's APIs" unless app_id
  raise ArgumentError, "Application Key (app_key) is required to interact with TFL's APIs" unless app_key

  # Set client defaults
  @host ||= 'https://api.tfl.gov.uk'
  @host = URI.parse(@host)

  # Create a global Net:HTTP instance
  @http = Net::HTTP.new(@host.host, @host.port)
  @http.use_ssl = true
  @http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  # Logging
  if @logger
    raise ArgumentError, 'logger parameter must be a Logger object' unless @logger.is_a?(Logger)
    raise ArgumentError, 'log_level cannot be set if using custom logger' if @log_level
    raise ArgumentError, 'log_location cannot be set if using custom logger' if @log_location
  else
    @log_level = Logger::INFO unless @log_level
    @log_location = STDOUT unless @log_location
    @logger = Logger.new(@log_location)
    @logger.level = @log_level
    @logger.datetime_format = '%F T%T%z'
    @logger.formatter = proc do |severity, datetime, _progname, msg|
      "[%s] %-6s %s \r\n" %  [datetime, severity, msg]
    end
  end
end

Public Instance Methods

accident_stats() click to toggle source

Creates an instance to the AccidentStats class by passing a reference to self

@return [TflApi::Client::AccidentStats] An object to AccidentStats subclass

# File lib/tfl_api_client/client.rb, line 103
def accident_stats
  TflApi::Client::AccidentStats.new(self)
end
air_quality() click to toggle source

Creates an instance to the AirQuality class by passing a reference to self

@return [TflApi::Client::AirQuality] An object to AirQuality subclass

# File lib/tfl_api_client/client.rb, line 111
def air_quality
  TflApi::Client::AirQuality.new(self)
end
bike_point() click to toggle source

Creates an instance to the BikePoint class by passing a reference to self

@return [TflApi::Client::BikePoint] An object to BikePoint subclass

# File lib/tfl_api_client/client.rb, line 119
def bike_point
  TflApi::Client::BikePoint.new(self)
end
cabwise() click to toggle source

Creates an instance to the Cabwise class by passing a reference to self

@return [TflApi::Client::Cabwise] An object to Cabwise subclass

# File lib/tfl_api_client/client.rb, line 135
def cabwise
  TflApi::Client::Cabwise.new(self)
end
cycle() click to toggle source

Creates an instance to the Cycle class by passing a reference to self

@return [TflApi::Client::Cycle] An object to Cycle subclass

# File lib/tfl_api_client/client.rb, line 127
def cycle
  TflApi::Client::Cycle.new(self)
end
get(path, query={}) click to toggle source

Performs a HTTP GET request to the api, based upon the given URI resource and any additional HTTP query parameters. This method will automatically inject the mandatory application id and application key HTTP query parameters.

@return [hash] HTTP response as a hash

# File lib/tfl_api_client/client.rb, line 162
def get(path, query={})
  request_json :get, path, query
end
inspect() click to toggle source

Overrides the inspect method to prevent the TFL Application ID and Key credentials being shown when the `inspect` method is called. The method will only print the important variables.

@return [String] String representation of the current object

# File lib/tfl_api_client/client.rb, line 172
def inspect
  "#<#{self.class.name}:0x#{(self.__id__ * 2).to_s(16)} " +
      "@host=#{host.to_s}, " +
      "@log_level=#{log_level}, " +
      "@log_location=#{log_location.inspect}>"
end
journey() click to toggle source

Creates an instance to the Journey class by passing a reference to self

@return [TflApi::Client::Journey] An object to Journey subclass

# File lib/tfl_api_client/client.rb, line 143
def journey
  TflApi::Client::Journey.new(self)
end
mode() click to toggle source

Creates an instance to the Mode class by passing a reference to self

@return [TflApi::Client::Mode] An object to Mode subclass

# File lib/tfl_api_client/client.rb, line 151
def mode
  TflApi::Client::Mode.new(self)
end

Private Instance Methods

format_request_uri(path, params) click to toggle source

Returns a full, well-formatted HTTP request URI that can be used to directly interact with the TFL API.

@param path [String] the path of the resource (not including the base url) to request @param params [Hash] Additional url params to be added to the request

@return [String] Full HTTP request URI

# File lib/tfl_api_client/client.rb, line 232
def format_request_uri(path, params)
  params.merge!({app_id: app_id, app_key: app_key})
  params_string = URI.encode_www_form(params)
  URI::HTTPS.build(host: host.host, path: URI.escape(path), query: params_string)
end
parse_response_json(response) click to toggle source

Parses the given response body as JSON, and returns a hash representation of the the response. Failure to successfully parse the response will result in an TflApi::Exceptions::ApiException being raised.

@param response [HTTPResponse] the HTTP response object

@return [HTTPResponse] HTTP response object

@raise [TflApi::Exceptions::ApiException] when trying to parse a malformed JSON response

# File lib/tfl_api_client/client.rb, line 248
def parse_response_json(response)
  begin
    JSON.parse(response.body)
  rescue JSON::ParserError
    raise TflApi::Exceptions::ApiException, logger, "Invalid JSON returned from #{host.host}"
  end
end
raise_exception(response) click to toggle source

Raises a child of TflApi::Exceptions::ApiException based upon the response code being classified as non-successful, i.e. a non 2xx response code. All non-successful responses will raise an TflApi::Exceptions::ApiException by default. Popular non-successful response codes are mapped to internal exceptions, for example a 404 response code would raise TflApi::Exceptions::NotFound.

@param response [HTTPResponse] the HTTP response object

@raise [TflApi::Exceptions::ApiException] when an error has occurred with TFL's API

# File lib/tfl_api_client/client.rb, line 266
def raise_exception(response)
  case response.code.to_i
    when 401
      raise TflApi::Exceptions::Unauthorized, logger
    when 403
      raise TflApi::Exceptions::Forbidden, logger
    when 404
      raise TflApi::Exceptions::NotFound, logger
    when 500
      raise TflApi::Exceptions::InternalServerError, logger
    when 503
      raise TflApi::Exceptions::ServiceUnavailable, logger
    else
      raise TflApi::Exceptions::ApiException, logger, "non-successful response (#{response.code}) was returned"
  end
end
request(method, path, params) click to toggle source

Creates and performs HTTP request by the request medium to the given path with any additional uri parameters. The method will return the HTTP response object upon completion.

@param method [Symbol] The type of HTTP request to make, e.g. :get @param path [String] the path of the resource (not including the base url) to request @param params [Hash] Additional url params to be added to the request

@return [HTTPResponse] HTTP response object

# File lib/tfl_api_client/client.rb, line 214
def request(method, path, params)
  full_path = format_request_uri(path, params)
  request = VERB_MAP[method.to_sym].new(full_path)
  # TODO - Enable when supporting other HTTP Verbs
  # request.set_form_data(params) unless method == :get

  @logger.debug "#{method.to_s.upcase} #{path}"
  @http.request(request)
end
request_json(method, path, params) click to toggle source

This method requests the given path via the given resource with the additional url params. All successful responses will yield a hash of the response body, whilst all other response types will raise a child of TflApi::Exceptions::ApiException. For example a 404 response would raise a TflApi::Exceptions::NotFound exception.

@param method [Symbol] The type of HTTP request to make, e.g. :get @param path [String] the path of the resource (not including the base url) to request @param params [Hash]

@return [HTTPResponse] HTTP response object

@raise [TflApi::Exceptions::ApiException] when an error has occurred with TFL's API

# File lib/tfl_api_client/client.rb, line 194
def request_json(method, path, params)
  response = request(method, path, params)

  if response.kind_of? Net::HTTPSuccess
    parse_response_json(response)
  else
    raise_exception(response)
  end
end