zendesk_api 0.1.7 → 0.1.8

data/.yardopts

@@ -1 +1 @@
---no-private --protected lib/**/*.rb - Readme.md
+--tag internal --hide-tag internal --no-private --protected lib/**/*.rb -e util/resource_handler.rb -e util/verb_handler.rb - Readme.md

data/Gemfile.lock

@@ -7,7 +7,7 @@ GIT
 PATH
   remote: .
   specs:
-    zendesk_api (0.1.6)
+    zendesk_api (0.1.8)
       faraday (>= 0.8.0)
       faraday_middleware (>= 0.8.7)
       hashie
@@ -20,6 +20,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     addressable (2.3.2)
+    bump (0.3.3)
     crack (0.3.1)
     diff-lcs (1.1.3)
     faraday (0.8.4)
@@ -54,6 +55,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  bump
   hashie!
   jruby-openssl
   rake

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rake/testtask'
 require 'bundler/gem_tasks'
+require 'bump/tasks'
 
 begin
   require 'rspec/core/rake_task'

data/Readme.md

@@ -151,6 +151,44 @@ ticket.new_record? # => true
 ticket.save # Will POST
 ```
 
+### Side-loading
+
+**Warning: this is an experimental feature. Abuse it and lose it.**
+
+To facilitate a smaller number of requests and easier manipulation of associated data we allow "side-loading", or inclusion, of selected resources.
+
+For example:
+A ZendeskAPI::Ticket is associated with ZendeskAPI::User through the requester_id field.
+API requests for that ticket return a structure similar to this:
+```json
+"ticket": {
+  "id": 1,
+  "url": "http.....",
+  "requester_id": 7,
+  ...
+}
+```
+
+Calling ZendeskAPI::Ticket#requester automatically fetches and loads the user referenced above (`/api/v2/users/7`).
+Using side-loading, however, the user can be partially loaded in the same request as the ticket.
+
+```ruby
+tickets = client.tickets.include(:users)
+# Or client.tickets(include: :users)
+# Does *NOT* make a request to the server since it is already loaded
+tickets.first.requester # => #<ZendeskAPI::User id=...>
+```
+
+OR
+
+```ruby
+ticket = client.tickets.find(:id => 1, :include => :users)
+ticket.requester # => #<ZendeskAPI::User id=...>
+```
+
+Currently, this feature is limited to only a few resources and their associations.
+They are documented on [developer.zendesk.com](http://developer.zendesk.com/documentation/rest_api/introduction.html#side-loading).
+
 ### Special case: Custom resources paths
 
 API endpoints such as tickets/recent or topics/show_many can be accessed through chaining.

data/lib/zendesk_api.rb

@@ -1,5 +1,4 @@
+module ZendeskAPI; end
+
 require 'zendesk_api/core_ext/inflection'
 require 'zendesk_api/client'
-
-module ZendeskAPI
-end

data/lib/zendesk_api/actions.rb

@@ -1,7 +1,7 @@
 module ZendeskAPI
   module Save
     # If this resource hasn't been deleted, then create or save it.
-    # Executes a POST if it is a {#new_record?}, otherwise a PUT.
+    # Executes a POST if it is a {Data#new_record?}, otherwise a PUT.
     # Merges returned attributes on success.
     # @return [Boolean] Success?
     def save(options={})
@@ -33,10 +33,13 @@ module ZendeskAPI
       true
     end
 
+    # Saves, raising an Argument error if it fails
+    # @raise [ArgumentError] if saving failed
     def save!(options={})
       save(options) || raise("Save failed")
     end
 
+    # Removes all cached associations
     def clear_associations
       self.class.associations.each do |association_data|
         name = association_data[:name]
@@ -44,6 +47,8 @@ module ZendeskAPI
       end
     end
 
+    # Saves associations
+    # Takes into account inlining, collections, and id setting on the parent resource.
     def save_associations
       self.class.associations.each do |association_data|
         association_name = association_data[:name]
@@ -71,7 +76,7 @@ module ZendeskAPI
     end
 
     # Finds a resource by an id and any options passed in.
-    # A custom path to search at can be passed into opts. It defaults to the {DataResource.resource_name} of the class. 
+    # A custom path to search at can be passed into opts. It defaults to the {Data.resource_name} of the class.
     # @param [Client] client The {Client} object to be used
     # @param [Hash] options Any additional GET parameters to be added
     def find(client, options = {})
@@ -115,6 +120,8 @@ module ZendeskAPI
         resource
       end
 
+      # Creates the resource, raising an ArgumentError if it fails
+      # @raise [ArgumentError] if the creation fails
       def create!(client, attributes={})
         c = create(client, attributes)
         c || raise("Create failed #{self} #{attributes}")

data/lib/zendesk_api/association.rb

@@ -2,6 +2,7 @@ require 'zendesk_api/helpers'
 
 module ZendeskAPI
   # Represents an association between two resources 
+  # @private
   class Association
     # @return [Hash] Options passed into the association
     attr_reader :options
@@ -35,7 +36,7 @@ module ZendeskAPI
       has_parent = namespace.size > 1 || (options[:with_parent] && @options.parent)
 
       if has_parent
-        parent_class = @options.parent ? @options.parent.class : ZendeskAPI.get_class(namespace[0])
+        parent_class = @options.parent ? @options.parent.class : ZendeskAPI.const_get(ZendeskAPI::Helpers.modulize_string(namespace[0]))
         parent_namespace = build_parent_namespace(parent_class, instance, options, original_options)
         namespace[1..1] = parent_namespace if parent_namespace
         namespace[0] = parent_class.resource_name
@@ -50,6 +51,7 @@ module ZendeskAPI
       namespace.join("/")
     end
 
+    # Tries to place side loads onto given resources.
     def side_load(resources, side_loads)
       key = "#{options.name}_id"
       plural_key = "#{Inflection.singular options.name.to_s}_ids"
@@ -138,6 +140,8 @@ module ZendeskAPI
   # * Commonly used resources are automatically side-loaded server side and sent along with their parent object.
   # * Associated resource ids are sent and are then loaded one-by-one into the parent collection.
   # * The association is represented with Rails' nested association urls (such as tickets/:id/groups) and are loaded that way.
+  #
+  # @private
   module Associations
     def self.included(base)
       base.send(:extend, ClassMethods)
@@ -156,6 +160,7 @@ module ZendeskAPI
       end
     end
 
+    # @private
     module ClassMethods
       include Rescue
 
@@ -174,10 +179,15 @@ module ZendeskAPI
       end
 
       # Represents a parent-to-child association between resources. Options to pass in are: class, path.
-      # @param [Symbol] resource_name The underlying resource name
-      # @param [Hash] opts The options to pass to the method definition.
-      def has(resource_name, class_level_options = {})
-        klass = get_class(class_level_options.delete(:class)) || get_class(resource_name)
+      # @param [Symbol] resource_name_or_class The underlying resource name or a class to get it from
+      # @param [Hash] class_level_options The options to pass to the method definition.
+      def has(resource_name_or_class, class_level_options = {})
+        if klass = class_level_options.delete(:class)
+          resource_name = resource_name_or_class
+        else
+          klass = resource_name_or_class
+          resource_name = klass.singular_resource_name
+        end
 
         class_level_association = {
           :class => klass,
@@ -229,18 +239,23 @@ module ZendeskAPI
       end
 
       # Represents a parent-to-children association between resources. Options to pass in are: class, path.
-      # @param [Symbol] resource The underlying resource name
-      # @param [Hash] opts The options to pass to the method definition.
-      def has_many(resource_name, class_level_opts = {})
-        klass = get_class(class_level_opts.delete(:class)) || get_class(Inflection.singular(resource_name.to_s))
+      # @param [Symbol] resource_name_or_class The underlying resource name or class to get it from
+      # @param [Hash] class_level_options The options to pass to the method definition.
+      def has_many(resource_name_or_class, class_level_options = {})
+        if klass = class_level_options.delete(:class)
+          resource_name = resource_name_or_class
+        else
+          klass = resource_name_or_class
+          resource_name = klass.resource_name
+        end
 
         class_level_association = {
           :class => klass,
           :name => resource_name,
-          :inline => class_level_opts.delete(:inline),
-          :path => class_level_opts.delete(:path),
-          :include => (class_level_opts.delete(:include) || klass.resource_name).to_s,
-          :include_key => (class_level_opts.delete(:include_key) || :id).to_s,
+          :inline => class_level_options.delete(:inline),
+          :path => class_level_options.delete(:path),
+          :include => (class_level_options.delete(:include) || klass.resource_name).to_s,
+          :include_key => (class_level_options.delete(:include_key) || :id).to_s,
           :singular => false
         }
 
@@ -292,47 +307,6 @@ module ZendeskAPI
           resource
         end
       end
-
-      # Allows using has and has_many without having class defined yet
-      # Guesses at Resource, if it's anything else and the class is later
-      # reopened under a different superclass, an error will be thrown
-      def get_class(resource)
-        return false if resource.nil?
-        res = ZendeskAPI::Helpers.modulize_string(resource.to_s)
-
-        begin
-          const_get(res)
-        rescue NameError, ArgumentError # ruby raises NameError, rails raises ArgumentError
-          ZendeskAPI.get_class(resource)
-        end
-      end
-    end
-  end
-
-  class << self
-    # Make sure Rails' overwriting of const_missing doesn't cause trouble
-    def const_missing(*args)
-      Object.const_missing(*args)
-    end
-
-    # Allows using has and has_many without having class defined yet
-    # Guesses at Resource, if it's anything else and the class is later
-    # reopened under a different superclass, an error will be thrown
-    def get_class(resource)
-      return false if resource.nil?
-      res = ZendeskAPI::Helpers.modulize_string(resource.to_s).split("::")
-
-      begin
-        res[1..-1].inject(ZendeskAPI.const_get(res[0])) do |iter, k|
-          begin
-            iter.const_get(k)
-          rescue
-            iter.const_set(k, Class.new(Resource))
-          end
-        end
-      rescue NameError
-        ZendeskAPI.const_set(res[0], Class.new(Resource))
-      end
     end
   end
 end

data/lib/zendesk_api/client.rb

@@ -17,6 +17,8 @@ require 'zendesk_api/middleware/response/parse_iso_dates'
 require 'zendesk_api/middleware/response/logger'
 
 module ZendeskAPI
+  # The top-level class that handles configuration and connection to the Zendesk API.
+  # Can also be used as an accessor to resource collections.
   class Client
     include Rescue
 
@@ -31,8 +33,14 @@ module ZendeskAPI
     def method_missing(method, *args, &block)
       method = method.to_s
       options = args.last.is_a?(Hash) ? args.pop : {}
-      return instance_variable_get("@#{method}") if !options.delete(:reload) && instance_variable_defined?("@#{method}")
-      instance_variable_set("@#{method}", ZendeskAPI::Collection.new(self, ZendeskAPI.get_class(Inflection.singular(method)), options))
+
+      @resource_cache[method] ||= {}
+
+      if !options[:reload] && (cached = @resource_cache[method][options.hash])
+        cached
+      else
+        @resource_cache[method][options.hash] = ZendeskAPI::Collection.new(self, ZendeskAPI.const_get(ZendeskAPI::Helpers.modulize_string(Inflection.singular(method))), options)
+      end
     end
 
     # Returns the current user (aka me)
@@ -42,6 +50,8 @@ module ZendeskAPI
       @current_user = users.find(:id => 'me')
     end
 
+    # Returns the current account
+    # @return [Hash] The attributes of the current account or nil
     def current_account(reload = false)
       return @current_account if @current_account && !reload
       @current_account = Hashie::Mash.new(connection.get('account/resolve').body)
@@ -50,6 +60,7 @@ module ZendeskAPI
     rescue_client_error :current_account
 
     # Returns the current locale
+    # @return [ZendeskAPI::Locale] Current locale or nil
     def current_locale(reload = false)
       return @locale if @locale && !reload
       @locale = locales.find(:id => 'current')
@@ -86,6 +97,8 @@ module ZendeskAPI
 
       @callbacks = []
 
+      @resource_cache = {}
+
       if logger = config.logger
         insert_callback do |env|
           if warning = env[:response_headers]["X-Zendesk-API-Warn"]
@@ -97,7 +110,7 @@ module ZendeskAPI
 
     # Creates a connection if there is none, otherwise returns the existing connection.
     #
-    # @returns [Faraday::Connection] Faraday connection for the client
+    # @return [Faraday::Connection] Faraday connection for the client
     def connection
       @connection ||= build_connection
       return @connection
@@ -111,7 +124,9 @@ module ZendeskAPI
 
     # show a nice warning for people using the old style api
     def self.check_deprecated_namespace_usage(attributes, name)
-      raise "un-nest '#{name}' from the attributes" if attributes[name].is_a?(Hash)
+      if attributes[name].is_a?(Hash)
+        raise "un-nest '#{name}' from the attributes"
+      end
     end
 
     protected
@@ -123,7 +138,7 @@ module ZendeskAPI
     # Uses middleware according to configuration options.
     #
     # Request logger if logger is not nil
-    # 
+    #
     # Retry middleware if retry is true
     def build_connection
       Faraday.new(config.options) do |builder|

data/lib/zendesk_api/collection.rb

@@ -1,7 +1,5 @@
 require 'zendesk_api/resource'
-require 'zendesk_api/resources/misc'
-require 'zendesk_api/resources/ticket'
-require 'zendesk_api/resources/user'
+require 'zendesk_api/resources'
 
 module ZendeskAPI
   # Represents a collection of resources. Lazily loaded, resources aren't
@@ -9,6 +7,7 @@ module ZendeskAPI
   class Collection
     include ZendeskAPI::Sideloading
 
+    # Options passed in that are automatically converted from an array to a comma-separated list.
     SPECIALLY_JOINED_PARAMS = [:ids, :only]
 
     include Rescue
@@ -19,6 +18,9 @@ module ZendeskAPI
     # @return [Faraday::Response] The last response
     attr_reader :response
 
+    # @return [Hash] query options
+    attr_reader :options
+
     # Creates a new Collection instance. Does not fetch resources.
     # Additional options are: verb (default: GET), path (default: resource param), page, per_page.
     # @param [Client] client The {Client} to use.
@@ -117,10 +119,15 @@ module ZendeskAPI
       self
     end
 
+    # Adds an item (or items) to the list of side-loaded resources to request
+    # @option sideloads [Symbol or String] The item(s) to sideload
     def include(*sideloads)
       self.tap { @includes.concat(sideloads.map(&:to_s)) }
     end
 
+    # Adds an item to this collection
+    # @option item [ZendeskAPI::Data] the resource to add
+    # @raise [ArgumentError] if the resource doesn't belong in this collection
     def <<(item)
       fetch
       if item.is_a?(Resource)
@@ -135,6 +142,7 @@ module ZendeskAPI
       end
     end
 
+    # The API path to this collection
     def path
       @association.generate_path(:with_parent => true)
     end
@@ -178,18 +186,6 @@ module ZendeskAPI
       @resources
     end
 
-    def set_page_and_count(body)
-      @count = (body["count"] || @resources.size).to_i
-      @next_page, @prev_page = body["next_page"], body["previous_page"]
-
-      if @next_page =~ /page=(\d+)/
-        @options["page"] = $1.to_i - 1
-      elsif @prev_page =~ /page=(\d+)/
-        @options["page"] = $1.to_i + 1
-      end
-    end
-
-
     rescue_client_error :fetch, :with => lambda { Array.new }
 
     # Alias for fetch(false)
@@ -218,12 +214,15 @@ module ZendeskAPI
       end
     end
 
+    # Replaces the current (loaded or not) resources with the passed in collection
+    # @option collection [Array] The collection to replace this one with
+    # @raise [ArgumentError] if any resources passed in don't belong in this collection
     def replace(collection)
       raise "this collection is for #{@resource_class}" if collection.any?{|r| !r.is_a?(@resource_class) }
       @resources = collection
     end
 
-    # Find the next page. Does one of three things: 
+    # Find the next page. Does one of three things:
     # * If there is already a page number in the options hash, it increases it and invalidates the cache, returning the new page number.
     # * If there is a next_page url cached, it executes a fetch on that url and returns the results.
     # * Otherwise, returns an empty array.
@@ -265,6 +264,7 @@ module ZendeskAPI
       @prev_page = nil
     end
 
+    # @private
     def to_ary; nil; end
 
     # Sends methods to underlying array of resources.
@@ -283,6 +283,8 @@ module ZendeskAPI
     end
 
     alias :orig_to_s :to_s
+
+    # @private
     def to_s
       if @resources
         @resources.inspect
@@ -290,5 +292,18 @@ module ZendeskAPI
         orig_to_s
       end
     end
+
+    private
+
+    def set_page_and_count(body)
+      @count = (body["count"] || @resources.size).to_i
+      @next_page, @prev_page = body["next_page"], body["previous_page"]
+
+      if @next_page =~ /page=(\d+)/
+        @options["page"] = $1.to_i - 1
+      elsif @prev_page =~ /page=(\d+)/
+        @options["page"] = $1.to_i + 1
+      end
+    end
   end
 end