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
Client
accessors
Client
accessors
Client
accessors
Client
accessors
Client
accessors
Client
accessors
Public Class Methods
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
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
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
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
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
Private Instance Methods
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
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
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
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
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