class ZendeskAPI::Client

The top-level class that handles configuration and connection to the Zendesk API. Can also be used as an accessor to resource collections.

Constants

GZIP_EXCEPTIONS

Attributes

callbacks[R]

@return [Array] Custom response callbacks

config[R]

@return [Configuration] Config instance

Public Class Methods

check_deprecated_namespace_usage(attributes, name) click to toggle source

show a nice warning for people using the old style api

# File lib/zendesk_api/client.rb, line 121
def self.check_deprecated_namespace_usage(attributes, name)
  if attributes[name].is_a?(Hash)
    raise "un-nest '#{name}' from the attributes"
  end
end
new() { |config| ... } click to toggle source

Creates a new {Client} instance and yields {#config}.

Requires a block to be given.

Does basic configuration constraints:

  • {Configuration#url} must be https unless {Configuration#allow_http} is set.

# File lib/zendesk_api/client.rb, line 88
def initialize
  raise ArgumentError, "block not given" unless block_given?

  @config = ZendeskAPI::Configuration.new
  yield config

  @callbacks = []
  @resource_cache = {}

  check_url

  config.retry = !!config.retry # nil -> false

  set_raise_error_when_rated_limited
  set_token_auth
  set_default_logger
  add_warning_callback
end

Public Instance Methods

connection() click to toggle source

Creates a connection if there is none, otherwise returns the existing connection.

@return [Faraday::Connection] Faraday connection for the client

# File lib/zendesk_api/client.rb, line 110
def connection
  @connection ||= build_connection
end
current_account(reload = false) click to toggle source

Returns the current account @return [Hash] The attributes of the current account or nil

# File lib/zendesk_api/client.rb, line 70
def current_account(reload = false)
  return @current_account if @current_account && !reload
  @current_account = SilentMash.new(connection.get('account/resolve').body)
end
current_locale(reload = false) click to toggle source

Returns the current locale @return [ZendeskAPI::Locale] Current locale or nil

# File lib/zendesk_api/client.rb, line 77
def current_locale(reload = false)
  return @locale if @locale && !reload
  @locale = locales.find(:id => 'current')
end
current_user(reload = false) click to toggle source

Returns the current user (aka me) @return [ZendeskAPI::User] Current user or nil

# File lib/zendesk_api/client.rb, line 63
def current_user(reload = false)
  return @current_user if @current_user && !reload
  @current_user = users.find(:id => 'me')
end
insert_callback(&block) click to toggle source

Pushes a callback onto the stack. Callbacks are executed on responses, last in the Faraday middleware stack. @param [Proc] block The block to execute. Takes one parameter, env.

# File lib/zendesk_api/client.rb, line 116
def insert_callback(&block)
  @callbacks << block
end
method_missing(method, *args, &block) click to toggle source

Handles resources such as ‘tickets’. Any options are passed to the underlying collection, except reload which disregards memoization and creates a new Collection instance. @return [Collection] Collection instance for resource

# File lib/zendesk_api/client.rb, line 37
def method_missing(method, *args, &block)
  method = method.to_s
  options = args.last.is_a?(Hash) ? args.pop : {}
  unless config.use_resource_cache
    resource_class = resource_class_for(method)
    raise "Resource for #{method} does not exist" unless resource_class
    return ZendeskAPI::Collection.new(self, resource_class, options)
  end

  @resource_cache[method] ||= { :class => nil, :cache => ZendeskAPI::LRUCache.new }
  if !options.delete(:reload) && (cached = @resource_cache[method][:cache].read(options.hash))
    cached
  else
    @resource_cache[method][:class] ||= resource_class_for(method)
    raise "Resource for #{method} does not exist" unless @resource_cache[method][:class]
    @resource_cache[method][:cache].write(options.hash, ZendeskAPI::Collection.new(self, @resource_cache[method][:class], options))
  end
end
respond_to?(method, *args) click to toggle source
Calls superclass method
# File lib/zendesk_api/client.rb, line 56
def respond_to?(method, *args)
  cache = @resource_cache[method]
  !!(cache.to_h[:class] || resource_class_for(method) || super)
end

Protected Instance Methods

build_connection() click to toggle source

Called by {#connection} to build a connection. Can be overwritten in a subclass to add additional middleware and make other configuration changes.

Uses middleware according to configuration options.

Request logger if logger is not nil

Retry middleware if retry is true

# File lib/zendesk_api/client.rb, line 145
def build_connection
  Faraday.new(config.options) do |builder|
    # response
    builder.use ZendeskAPI::Middleware::Response::RaiseError
    builder.use ZendeskAPI::Middleware::Response::Callback, self
    builder.use ZendeskAPI::Middleware::Response::Logger, config.logger if config.logger
    builder.use ZendeskAPI::Middleware::Response::ParseIsoDates
    builder.use ZendeskAPI::Middleware::Response::ParseJson
    builder.use ZendeskAPI::Middleware::Response::SanitizeResponse
    adapter = config.adapter || Faraday.default_adapter

    unless GZIP_EXCEPTIONS.include?(adapter)
      builder.use ZendeskAPI::Middleware::Response::Gzip
      builder.use ZendeskAPI::Middleware::Response::Deflate
    end

    set_authentication(builder, config)

    if config.cache
      builder.use ZendeskAPI::Middleware::Request::EtagCache, :cache => config.cache
    end

    builder.use ZendeskAPI::Middleware::Request::Upload
    builder.request :multipart
    builder.use ZendeskAPI::Middleware::Request::EncodeJson

    # Should always be first in the stack
    if config.retry
      builder.use ZendeskAPI::Middleware::Request::Retry,
                  :logger => config.logger,
                  :retry_codes => config.retry_codes,
                  :retry_on_exception => config.retry_on_exception
    end
    if config.raise_error_when_rate_limited
      builder.use ZendeskAPI::Middleware::Request::RaiseRateLimited, :logger => config.logger
    end

    builder.adapter(*adapter, &config.adapter_proc)
  end
end

Private Instance Methods

add_warning_callback() click to toggle source
# File lib/zendesk_api/client.rb, line 226
def add_warning_callback
  return unless logger = config.logger

  insert_callback do |env|
    if warning = env[:response_headers]["X-Zendesk-API-Warn"]
      logger.warn "WARNING: #{warning}"
    end
  end
end
check_url() click to toggle source
# File lib/zendesk_api/client.rb, line 193
def check_url
  if !config.allow_http && !config.url.start_with?('https://')
    raise ArgumentError, "zendesk_api is ssl only; url must begin with https://"
  end
end
resource_class_for(method) click to toggle source
# File lib/zendesk_api/client.rb, line 188
def resource_class_for(method)
  resource_name = ZendeskAPI::Helpers.modulize_string(Inflection.singular(method.to_s.gsub(/\W/, '')))
  ZendeskAPI::Association.class_from_namespace(resource_name)
end
set_authentication(builder, config) click to toggle source

See lostisland.github.io/faraday/middleware/authentication

# File lib/zendesk_api/client.rb, line 237
def set_authentication(builder, config)
  if config.access_token && !config.url_based_access_token
    builder.request :authorization, "Bearer", config.access_token
  elsif config.access_token
    builder.use ZendeskAPI::Middleware::Request::UrlBasedAccessToken, config.access_token
  else
    builder.request :authorization, :basic, config.username, config.password
  end
end
set_default_logger() click to toggle source
# File lib/zendesk_api/client.rb, line 218
def set_default_logger
  if config.logger.nil? || config.logger == true
    require 'logger'
    config.logger = Logger.new($stderr)
    config.logger.level = Logger::WARN
  end
end
set_raise_error_when_rated_limited() click to toggle source
# File lib/zendesk_api/client.rb, line 199
def set_raise_error_when_rated_limited
  config.raise_error_when_rate_limited = if config.retry
    false
  else
    !!config.raise_error_when_rate_limited
  end
end
set_token_auth() click to toggle source
# File lib/zendesk_api/client.rb, line 207
def set_token_auth
  return if config.password || config.token.nil?

  if config.username.nil?
    raise ArgumentError, "you need to provide a username when using API token auth"
  else
    config.password = config.token
    config.username += "/token" unless config.username.end_with?("/token")
  end
end