zendesk_api 0.3.14 → 0.4.0.rc1

data/.yardopts

@@ -1,8 +1,12 @@
 --tag internal
 --hide-tag internal
 --no-private
---protected lib/**/*.rb
+--protected
+--embed-mixins
 --load ./util/resource_handler.rb
 --load ./util/verb_handler.rb
+--exclude lib/zendesk_api/console
+--exclude lib/zendesk_api/server
+-r Readme.md
+lib/**/*.rb
 -
-Readme.md

data/Gemfile

@@ -3,10 +3,9 @@ source 'https://rubygems.org'
 # gem "bundler", "~> 1.2.0"
 # ruby "1.9.3"
 
-gem "simplecov", :platforms => :ruby_19, :group => :development
+gem "simplecov", :platforms => :ruby_19, :group => :test
 gem "jruby-openssl", :platforms => :jruby
 gem "multipart-post", :git => "https://github.com/steved555/multipart-post.git"
-gem "multi_json", :group => :test
 
 group :server do
   gem "thin"
@@ -36,4 +35,6 @@ group :console do
   gem "ripl"
 end
 
+gem "json", :group => :test, :platform => :ruby_18
+
 gemspec

data/Gemfile.lock

@@ -7,13 +7,13 @@ GIT
 PATH
   remote: .
   specs:
-    zendesk_api (0.3.14)
+    zendesk_api (0.4.0.rc1)
       faraday (>= 0.8.0)
       faraday_middleware (>= 0.8.7)
       hashie (>= 1.2)
       inflection
-      json
       mime-types
+      multi_json
       multipart-post
 
 GEM
@@ -55,7 +55,7 @@ GEM
     fssm (0.2.10)
     haml (4.0.1)
       tilt
-    hashie (2.0.5)
+    hashie (2.0.4)
     i18n (0.6.1)
     inflection (1.0.0)
     jruby-openssl (0.8.7)
@@ -130,8 +130,8 @@ DEPENDENCIES
   database_cleaner
   haml
   jruby-openssl
+  json
   mongoid
-  multi_json
   multipart-post!
   newrelic_rpm
   rack-ssl-enforcer

data/Readme.md

@@ -4,11 +4,11 @@
 
 This client **only** supports Zendesk's v2 API.  Please see our [API documentation](http://developer.zendesk.com) for more information.
 
-## Additional Documentation
+## Documentation
 
-Additional documentation can be found on our [documentation site](https://zendesk-api.herokuapp.com/doc/index.html) and [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki).
+Please check out the [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki), [class documentation](https://zendesk-api.herokuapp.com/doc/index.html), and [issues](https://github.com/zendesk/zendesk_api_client_rb/issues) before reporting a bug or asking for help.
 
-## Important Notice
+## Important Notices
 
 * Version 0.0.5 brings with it a change to the top-level namespace. All references to Zendesk should now use ZendeskAPI.
 * Version 0.3.0 changed the license from MIT to Apache Version 2.
@@ -32,271 +32,6 @@ Add it to your Gemfile
 
 and follow normal [Bundler](http://gembundler.com/) installation and execution procedures.
 
-## Configuration
-
-Configuration is done through a block returning an instance of ZendeskAPI::Client.
-The block is mandatory and if not passed, an ArgumentError will be thrown.
-
-```ruby
-require 'zendesk_api'
-
-client = ZendeskAPI::Client.new do |config|
-  # Mandatory:
-
-  config.url = "<- your-zendesk-url ->" # e.g. https://mydesk.zendesk.com/api/v2
-
-  config.username = "login.email@zendesk.com"
-
-  # Choose one of the following depending on your authentication choice
-  config.token = "your zendesk token"
-  config.password = "your zendesk password"
-
-  # Optional:
-
-  # Retry uses middleware to notify the user
-  # when hitting the rate limit, sleep automatically,
-  # then retry the request.
-  config.retry = true
-
-  # Logger prints to STDERR by default, to e.g. print to stdout:
-  require 'logger'
-  config.logger = Logger.new(STDOUT)
-
-  # Changes Faraday adapter
-  # config.adapter = :patron
-
-  # Merged with the default client options hash
-  # config.client_options = { :ssl => false }
-
-  # When getting the error 'hostname does not match the server certificate'
-  # use the API at https://yoursubdomain.zendesk.com/api/v2
-end
-```
-
-Note: This ZendeskAPI API client only supports basic authentication at the moment.
-
-## Usage
-
-The result of configuration is an instance of ZendeskAPI::Client which can then be used in two different methods.
-
-One way to use the client is to pass it in as an argument to individual classes.
-
-```ruby
-ZendeskAPI::Ticket.new(client, :id => 1, :priority => "urgent") # doesn't actually send a request, must explicitly call #save
-ZendeskAPI::Ticket.create(client, :subject => "Test Ticket", :comment => { :value => "This is a test" }, :submitter_id => client.current_user.id, :priority => "urgent")
-ZendeskAPI::Ticket.find(client, :id => 1)
-ZendeskAPI::Ticket.delete(client, :id => 1)
-```
-
-Another way is to use the instance methods under client.
-
-```ruby
-client.tickets.first
-client.tickets.find(:id => 1)
-client.tickets.create(:subject => "Test Ticket", :comment => { :value => "This is a test" }, :submitter_id => client.current_user.id, :priority => "urgent")
-client.tickets.delete(:id => 1)
-```
-
-The methods under ZendeskAPI::Client (such as .tickets) return an instance of ZendeskAPI::Collection a lazy-loaded list of that resource.
-Actual requests may not be sent until an explicit ZendeskAPI::Collection#fetch, ZendeskAPI::Collection#to_a, or an applicable methods such
-as #each.
-
-### Caveats
-
-Resource updating is implemented by sending only the `changed?` attributes to the server (see `ZendeskAPI::TrackChanges`).
-Unfortunately, this module only hooks into `Hash` meaning any changes to an `Array`not resulting in a new instance will not be tracked and sent.
-
-```
-zendesk_api_client_rb $ bundle console
-> a = ZendeskAPI::Trackie.new(:tags => []).tap(&:clear_changes)
-> a.changed?(:tags)
- => false
-> a.tags << "my_new_tag"
- => ["my_new_tag"]
-> a.changed?(:tags)
- => false
-> a.tags += %w{my_other_tag}
- => ["my_new_tag", "my_other_tag"]
-> a.changed?(:tags)
- => true
-```
-
-### Pagination
-
-ZendeskAPI::Collections can be paginated:
-
-```ruby
-tickets = client.tickets.page(2).per_page(3)
-next_page = tickets.next
-previous_page = tickets.prev
-```
-
-Iteration over all resources and pages is handled by Collection#each_page
-
-```ruby
-client.tickets.each_page do |resource|
-  # all resources will be yielded
-end
-```
-
-If given a block with two arguments, the page is also passed in.
-
-```ruby
-client.tickets.each_page do |resource, page|
-  # all resources will be yielded along with the page
-end
-```
-
-### Callbacks
-
-Callbacks can be added to the ZendeskAPI::Client instance and will be called (with the response env) after all response middleware on a successful request.
-
-```ruby
-client.insert_callback do |env|
-  puts env[:response_headers]
-end
-```
-
-### Resource management
-
-Individual resources can be created, modified, saved, and destroyed.
-
-```ruby
-ticket = client.tickets[0] # ZendeskAPI::Ticket.find(client, :id => 1)
-ticket.priority = "urgent"
-ticket.attributes # => { "priority" => "urgent" }
-ticket.save # Will PUT => true
-ticket.destroy # => true
-
-ZendeskAPI::Ticket.new(client, { :priority => "urgent" })
-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-\(beta\)).
-
-### Search
-
-Searching is done through the client. Returned is an instance of ZendeskAPI::Collection:
-
-```ruby
-client.search(:query => "my search query") # /api/v2/search.json?query=...
-client.users.search(:query => "my new query")  # /api/v2/users/search.json?query=...
-```
-
-### Special case: Custom resources paths
-
-API endpoints such as tickets/recent or topics/show_many can be accessed through chaining.
-They will too return an instance of ZendeskAPI::Collection.
-
-```ruby
-client.tickets.recent
-client.topics.show_many(:verb => :post, :ids => [1, 2, 3])
-```
-
-### Special Case: Current user
-
-Use either of the following to obtain the current user instance:
-
-```ruby
-client.users.find(:id => 'me')
-client.current_user
-```
-
-### Special Case: Importing a ticket
-
-Bulk importing tickets allows you to move large amounts of data into Zendesk.
-
-```ruby
-ticket = ZendeskAPI::Ticket.import(client, :subject => "Help", :comments => [{ :author_id => 19, :value => "This is a comment" }])
-```
-
-http://developer.zendesk.com/documentation/rest_api/ticket_import.html
-
-### Attaching files
-
-Files can be attached to ticket comments using either a path or the File class and will
-be automatically uploaded and attached.
-
-```ruby
-ticket = ZendeskAPI::Ticket.new(client, :comment => { :value => "attachments" })
-ticket.comment.uploads << "img.jpg"
-ticket.comment.uploads << File.new("img.jpg")
-ticket.save
-```
-
-## Extras
-
-The following projects are still works in progress and require checking out the repository,
-using ruby 1.9.3, and running `bundle install`.
-
-### Zendesk API Test Server
-
-Included in this repository is the code for the [Zendesk API Tester](https://zendesk-api.herokuapp.com/) website.
-
-```sh
-bin/zendesk server --help
-```
-
-Additional Dependencies:
-
-* sinatra
-* sinatra-contrib
-* haml
-* compass
-* coderay
-* coderay_bash
-* redcarpet
-* mongoid (and a working MongoDB instance)
-
-### Zendesk Console
-
-WIP
-
-```sh
-bin/zendesk console --help
-```
-
-Additional Dependencies:
-
-* ripl
-
 ## Note on Patches/Pull Requests
 1. Fork the project.
 2. Make your feature addition or bug fix.

data/lib/zendesk_api/actions.rb

@@ -4,7 +4,7 @@ module ZendeskAPI
     # Executes a POST if it is a {Data#new_record?}, otherwise a PUT.
     # Merges returned attributes on success.
     # @return [Boolean] Success?
-    def save(options={})
+    def save!(options={})
       return false if respond_to?(:destroyed?) && destroyed?
 
       if new_record?
@@ -20,13 +20,7 @@ module ZendeskAPI
       save_associations
 
       @response = @client.connection.send(method, req_path) do |req|
-        req.body = if self.class.unnested_params
-          attributes.changes
-        else
-          {self.class.singular_resource_name.to_sym => attributes.changes}
-        end
-
-        req.body.merge!(@global_params)
+        req.body = attributes_for_save.merge(@global_params)
       end
 
       @attributes.replace @attributes.deep_merge(@response.body[self.class.singular_resource_name] || {})
@@ -35,10 +29,14 @@ 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")
+    # Saves, returning false if it fails and attaching the errors
+    def save(options={})
+      save!(options)
+    rescue ZendeskAPI::Error::RecordInvalid => e
+      @errors = e.errors
+      false
+    rescue ZendeskAPI::Error::ClientError
+      false
     end
 
     # Removes all cached associations
@@ -71,8 +69,6 @@ module ZendeskAPI
   end
 
   module Read
-    include Rescue
-
     def self.extended(klass)
       klass.send(:include, ZendeskAPI::Sideloading)
     end
@@ -81,7 +77,7 @@ module ZendeskAPI
     # 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 = {})
+    def find!(client, options = {})
       @client = client # so we can use client.logger in rescue
 
       raise ArgumentError, "No :id given" unless options[:id] || options["id"] || ancestors.include?(SingularResource)
@@ -96,11 +92,15 @@ module ZendeskAPI
 
       new(client, response.body[singular_resource_name]).tap do |resource|
         resource.set_includes(resource, includes, response.body)
-        resource.attributes.clear_changes
       end
     end
 
-    rescue_client_error :find
+    # Finds, returning nil if it fails
+    def find(client, options = {})
+      find!(client, options)
+    rescue ZendeskAPI::Error::ClientError => e
+      nil
+    end
   end
 
   module Create
@@ -111,32 +111,23 @@ module ZendeskAPI
     end
 
     module ClassMethods
-      include Rescue
-
       # Create a resource given the attributes passed in.
       # @param [Client] client The {Client} object to be used
       # @param [Hash] attributes The attributes to create.
-      def create(client, attributes = {})
+      def create!(client, attributes = {})
         ZendeskAPI::Client.check_deprecated_namespace_usage attributes, singular_resource_name
-        resource = new(client, attributes)
-        return unless resource.save
-        resource
+        new(client, attributes).tap(&:save!)
       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}")
+      def create(client, attributes = {})
+        create!(client, attributes)
+      rescue ZendeskAPI::Error::ClientError
+        nil
       end
-
-      rescue_client_error :create
     end
   end
 
   module Destroy
-    include Rescue
-
     def self.included(klass)
       klass.extend(ClassMethod)
     end
@@ -148,21 +139,23 @@ module ZendeskAPI
 
     # If this resource hasn't already been deleted, then do so.
     # @return [Boolean] Successful?
-    def destroy
+    def destroy!
       return false if destroyed? || new_record?
       @client.connection.delete(url || path)
       @destroyed = true
     end
 
-    rescue_client_error :destroy, :with => false
+    def destroy
+      destroy!
+    rescue ZendeskAPI::Error::ClientError
+      false
+    end
 
     module ClassMethod
-      include Rescue
-
       # Deletes a resource given the id passed in.
       # @param [Client] client The {Client} object to be used
       # @param [Hash] opts The optional parameters to pass. Defaults to {}
-      def destroy(client, opts = {})
+      def destroy!(client, opts = {})
         @client = client # so we can use client.logger in rescue
         association = opts.delete(:association) || Association.new(:class => self)
 
@@ -173,34 +166,46 @@ module ZendeskAPI
         true
       end
 
-      rescue_client_error :destroy, :with => false
+      def destroy(client, attributes = {})
+        destroy!(client, attributes)
+      rescue ZendeskAPI::Error::ClientError
+        false
+      end
     end
   end
 
   module Update
-    include Rescue
     include Save
 
     def self.included(klass)
       klass.extend(ClassMethod)
     end
 
-    rescue_client_error :save, :with => false
-
     module ClassMethod
-      include Rescue
-
       # Updates  a resource given the id passed in.
       # @param [Client] client The {Client} object to be used
       # @param [Hash] attributes The attributes to update. Default to {}
       def update(client, attributes = {})
+        update!(client, attributes)
+      rescue ZendeskAPI::Error::ClientError
+        false
+      end
+
+      def update!(client, attributes = {})
         ZendeskAPI::Client.check_deprecated_namespace_usage attributes, singular_resource_name
-        resource = new(client, {:id => attributes.delete(:id), :global => attributes.delete(:global)})
+        resource = new(client, { :id => attributes.delete(:id), :global => attributes.delete(:global) })
         resource.attributes.merge!(attributes)
-        resource.save
+        resource.tap(&:save!)
       end
 
-      rescue_client_error :update, :with => false
+      private
+
+      def _update(client, attributes = {})
+        ZendeskAPI::Client.check_deprecated_namespace_usage attributes, singular_resource_name
+        resource = new(client, { :id => attributes.delete(:id), :global => attributes.delete(:global) })
+        resource.attributes.merge!(attributes)
+        resource
+      end
     end
   end
 end