desk_api 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6883196206272d0b4c6d3bb2f05162fc54b69f2f
-  data.tar.gz: ee8ed10269afb814092436c08fe175a630c6e152
+  metadata.gz: 418fce5029af0f83478582714488c4b29717deb2
+  data.tar.gz: 8be391f681e41a896d49ac74b64daa20878aacbc
 SHA512:
-  metadata.gz: 0be30c22b23542152d31eb01cd93eaae53eee661c775792922db110069084e1ef579a669edb72c98e95f44eaf1768f4ada722f2ee153a2131057bbe2d544b830
-  data.tar.gz: d8570d5cffca4ab9b65b77d5ac6ab06f1e6f0490cde0fa28f868f2a6fe71a723f7718b1386cb88460e2b8098895872c45fbcc97694f45a5aebdf926684ee81ee
+  metadata.gz: bfd58a478541754852d65f8f66508354c51b9250fd26f77e157818905f592c4fa3ba654dcf58be463ed038e3037ffd5a244a613927e21b078d716fe5818260d8
+  data.tar.gz: 865c292b84e95f563311ba8dd3bd4dc8b73c60fca0bcc7319ffe6bd69db612b90438e4f50107227428d2ce3c7c30552e3d52a694e7918072d712e7045cfca6dc

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2013-2014, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  * Neither the name of Salesforce.com nor the names of its contributors may be
+    used to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,12 +1,5 @@
 # DeskApi a client for APIv2
-
-[![Build Status](https://secure.travis-ci.org/tstachl/desk_api.png)](http://travis-ci.org/tstachl/desk_api)
-[![Coverage Status](https://coveralls.io/repos/tstachl/desk_api/badge.png?branch=develop)](https://coveralls.io/r/tstachl/desk_api?branch=develop)
-[![Dependency Status](https://gemnasium.com/tstachl/desk_api.png)](https://gemnasium.com/tstachl/desk_api)
-
-___
-## An Awesomely Unofficial Desk API Client
-___
+## An Awesomely (Un)official Desk API Client
 
 DeskApi takes the capabilities of the Desk.com API and wraps them up in a Ruby
 client so that it's easy-as-pie to get working with your support site's API.
@@ -14,28 +7,68 @@ client so that it's easy-as-pie to get working with your support site's API.
 Desk publishes a changelog monthly, which you can keep up with at
 [dev.desk.com/API/changelog](http://dev.desk.com/API/changelog).
 
-We do our best to keep DeskApi, but please
-don't hesitate to open an [issue](https://github.com/tstachl/desk/issues) or send a [pull request](https://github.com/tstachl/desk/pulls) if you find a bug or would like to new functionality added.
-
+We do our best to keep DeskApi, but please don't hesitate to open an
+[issue](https://github.com/forcedotcom/salesforce-deskcom-api/issues) or send a
+[pull request](https://github.com/forcedotcom/salesforce-deskcom-api/pulls)
+if you find a bug or would like to new functionality added.
 
-___
 ## Getting Started
-___
-
 ### Installation
+
 Easy!
 
 ```ruby
 gem install desk_api
 ```
-___
+
 ### Configuration
 
-There are two different ways to configure DeskApi to send and receive requests:
+#### Authentication Mechanism
+
+The desk.com API allows you to access data using two authentication mechanisms:
+
+##### Basic Authentication
+
+- Username
+- Password
+- Subdomain or Endpoint
+
+##### OAuth 1.0a
+
+- Consumer Key
+- Consumer Secret
+- Access Token
+- Access Token Secret
+- Subdomain or Endpoint
+
+#### Trust is our #1 value
+
+Whatever option or method you choose, please make sure to **never put your
+credentials in your source code**. This makes them available to everyone
+with read access to your source, it makes your code harder to maintain and
+is just overall a bad idea. There are many alternatives, including configuration
+files, environmental variables, ...
+
+#### First Environmental Variables
+
+`DeskApi` is automatically configured if you choose to use environmental
+variables. There are 8 possible variables but you don't have to set all of them.
+Based on the authentication mechanism you prefer you'll only have to specify:
+
+```bash
+export DESK_USERNAME=thomas@example.com
+export DESK_PASSWORD=somepassword
+export DESK_CONSUMER_KEY=CONSUMER_KEY
+export DESK_CONSUMER_SECRET=CONSUMER_SECRET
+export DESK_TOKEN=TOKEN
+export DESK_TOKEN_SECRET=TOKEN_SECRET
+export DESK_SUBDOMAIN=devel
+export DESK_ENDPOINT=https://devel.desk.com
+```
 
-#### First Configuration Option
+#### Second Configuration Option
 
-Configure `DeskApi` itself to send/receive requests by calling the `configure` 
+Configure `DeskApi` itself to send/receive requests by calling the `configure`
 method to set up your authentication credentials:
 
 ```ruby
@@ -59,7 +92,7 @@ DeskApi.patch '/api/v2/topics/1', name: 'Changed the Topic Name'
 DeskApi.delete '/api/v2/topics/1'
 ```
 
-#### Second Configuration Option
+#### Third Configuration Option
 
 Initialize a new `DeskApi::Client` to send/receive requests
 
@@ -84,17 +117,13 @@ response = client.patch '/api/v2/topics/1', name: 'Changed the Topic Name'
 response = client.delete '/api/v2/topics/1'
 ```
 
-
-___
 ## Resources
-___
 
 Resources are automatically discovered by the DeskApi. When requesting a
 resource from DeskAPI, the client sends the request and returns a
 `DeskApi::Resource`. If the client receives an error back from the API a
 `DeskApi::Error` is raised.
 
-___
 ### Create Read Update Delete
 
 One of the most important features; we support creating, updating and deleting
@@ -133,7 +162,7 @@ rescue DeskApi::Error::MethodNotAllowed => e
   # too bad
 end
 ```
-___
+
 ### Getters & Setters
 
 As you have seen in prior examples for each field on the resource we create a
@@ -161,7 +190,7 @@ rescue DeskApi::Error::MethodNotAllowed
   # too bad
 end
 ```
-___
+
 ### Find
 
 The method `by_url` can be called on the client, for backwards compatability we
@@ -187,7 +216,7 @@ collection `DeskApi.cases.find 1` the path will look like this:
 | `DeskApi.cases.search(subject: 'Test').entries.find(1)`     | `/api/v2/cases/1`           |
 | `DeskApi.cases.entries.first.replies.find(1)`               | `/api/v2/cases/1/replies/1` |
 | `DeskApi.cases.entries.first.replies.entries.first.find(1)` | `/api/v2/cases/1/replies/1` |
-___
+
 ### Pagination
 
 As mentioned above you can also navigate between resources and pages of
@@ -214,7 +243,7 @@ last_page = previous_page.last
 # or go to the first page
 first_page = last_page.first
 ```
-___
+
 ### `all` and `each_page`
 
 As a recent addition we made it even easier to navigate through all the pages.
@@ -231,7 +260,7 @@ end
 
 Both methods use the max `per_page` for the API endpoint for that particular
 resource.
-___
+
 ### List params
 
 Some lists allow for additional params like [cases](http://dev.desk.com/API/cases/#list).
@@ -248,7 +277,7 @@ customers_cases = DeskApi.cases(customer_id: 1)
 # fetch cases for the filter with id 1
 filters_cases = DeskApi.cases(filter_id: 1)
 ```
-___
+
 ### Sorting
 
 There is a maximum `page` limit on some Desk.com API endpoints. As of right now
@@ -271,11 +300,13 @@ To work around page limits, you can specify `sort_field` and `sort_direction`
 # fetch cases sorted by updated_at direction desc
 sorted_cases = DeskApi.cases(sort_field: :updated_at, sort_direction: :desc)
 ```
-___
+
 ### Links
 
-Once a `DeskApi::Resource` has loaded, its [linked resources](http://dev.desk.com/API/using-the-api/#relationships) can be retrieved
-by calling the linked resource as a method of the `DeskApi::Resource`, e.g., 
+Once a `DeskApi::Resource` has loaded, its
+[linked resources](http://dev.desk.com/API/using-the-api/#relationships)
+can be retrieved by calling the linked resource as a method of the
+`DeskApi::Resource`, e.g.,
 
 ```ruby
 # Get a ticket
@@ -302,7 +333,7 @@ user_name = DeskApi.
               sent_by.
               name
 ```
-___
+
 ### Lazy loading
 
 Resources are lazy loaded. This means that requests are only sent when you
@@ -318,12 +349,13 @@ end
 # it'll send a request
 DeskApi.cases.page == 1
 ```
-___
+
 ### Embedding
 
-Some endpoints support [embedding](http://dev.desk.com/API/using-the-api/#embedding) related resources. E.g., when getting a list
-of cases from `/api/v2/cases` you can embed the customer on each case by adding
-`embed=` to the query string: `/api/v2/cases?embed=customer`
+Some endpoints support [embedding](http://dev.desk.com/API/using-the-api/#embedding)
+related resources. E.g., when getting a list of cases from `/api/v2/cases` you
+can embed the customer on each case by adding `embed=` to the query
+string: `/api/v2/cases?embed=customer`
 
 The client supports this: `tickets_and_customers = DeskApi.cases.embed(:customer)`
 
@@ -361,7 +393,7 @@ customer = my_case.customer
 assigned_user = my_case.assigned_user
 assigned_group = my_case.assigned_group
 ```
-___
+
 ### API Errors
 
 Sometimes the API is going to return errors, eg. Validation Error. In these
@@ -384,28 +416,32 @@ Please also have a look at all
 [desk.com API errors](http://dev.desk.com/API/using-the-api/#status-codes) and
 their respective meanings.
 
-___
 ## License
-___
-
-(The MIT License)
-
-Copyright (c) 2013-2014 Thomas Stachl <tstachl@salesforce.com>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the 'Software'), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Copyright (c) 2013-2014, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  * Neither the name of Salesforce.com nor the names of its contributors may be
+    used to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/desk.rb

@@ -1 +1,29 @@
-require File.dirname(__FILE__) + '/desk_api'
+# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice, this
+#     list of conditions and the following disclaimer.
+#
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+#   * Neither the name of Salesforce.com nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require File.dirname(__FILE__) + '/desk_api'

data/lib/desk_api.rb

@@ -1,8 +1,55 @@
+# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice, this
+#     list of conditions and the following disclaimer.
+#
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+#   * Neither the name of Salesforce.com nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
 require 'uri'
 require 'faraday'
 require 'forwardable'
 require 'addressable/uri'
 
+# {DeskApi} allows for easy interaction with Desk.com's API.
+# It is the top level namespace and delegates all missing
+# methods to an automatically created client. This allows
+# you to use {DeskApi} as a client which is not recommended
+# if you have to connect to multiple Desk.com sites.
+#
+# @author    Thomas Stachl <tstachl@salesforce.com>
+# @copyright Copyright (c) 2013-2014 Salesforce.com
+# @license   BSD 3-Clause License
+#
+# @example configure the {DeskApi} client
+#   DeskApi.configure |config|
+#     config.username = 'user@example.com'
+#     config.password = 'mysecretpassword'
+#     config.endpoint = 'https://example.desk.com'
+#   end
+#
+# @example use {DeskApi} to send requests
+#   my_cases = DeskApi.cases # GET '/api/v2/cases'
 module DeskApi
   require 'desk_api/version'
   require 'desk_api/configuration'
@@ -11,18 +58,23 @@ module DeskApi
   class << self
     include DeskApi::Configuration
 
-    # Delegate to a DeskApi::Client
+    # Returns the default {DeskApi::Client}
     #
+    # @param options [Hash] optional configuration options
     # @return [DeskApi::Client]
     def client
-      return @client if instance_variable_defined?(:@client) && @client.hash == options.hash
+      return @client if defined?(:@client) && @client.hash == options.hash
       @client = DeskApi::Client.new(options)
     end
 
-    def method_missing(method_name, *args, &block)
-      client.send(method_name, *args, &block)
+    # Delegates missing methods to the default {DeskApi::Client}
+    #
+    # @return [DeskApi::Resource]
+    def method_missing(method, *args, &block)
+      client.send(method, *args, &block)
     end
   end
 
-  setup
+  # immediately reset the default client
+  reset!
 end

data/lib/desk_api/client.rb

@@ -1,61 +1,118 @@
+# Copyright (c) 2013-2014, Salesforce.com, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#   * Redistributions of source code must retain the above copyright notice, this
+#     list of conditions and the following disclaimer.
+#
+#   * Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+#   * Neither the name of Salesforce.com nor the names of its contributors may be
+#     used to endorse or promote products derived from this software without
+#     specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
 require 'desk_api/resource'
 require 'desk_api/error/parser_error'
 
-class DeskApi::Client
-  include DeskApi::Configuration
-
-  # Initializes a new Client object
+module DeskApi
+  # The {DeskApi::Client} builds and performs the
+  # http request using Faraday and the configured
+  # adapter. It includes and has full access to
+  # the configuration module.
   #
-  # @param options [Hash]
-  # @return [DeskApi::Client]
-  def initialize(options = {})
-    DeskApi::Configuration.keys.each do |key|
-      instance_variable_set(:"@#{key}", options[key] || DeskApi.instance_variable_get(:"@#{key}"))
-    end
-  end
+  # @author    Thomas Stachl <tstachl@salesforce.com>
+  # @copyright Copyright (c) 2013-2014 Salesforce.com
+  # @license   BSD 3-Clause License
+  class Client
+    include DeskApi::Configuration
 
-  # Perform an HTTP DELETE request
-  def delete(path, params = {})
-    request(:delete, path, params)
-  end
-
-  # Perform an HTTP GET request
-  def get(path, params = {})
-    request(:get, path, params)
-  end
+    # Initializes a new client object
+    #
+    # @param options [Hash] optional configuration hash
+    # @return [DeskApi::Client] the new client
+    def initialize(options = {})
+      DeskApi::Configuration.keys.each do |key|
+        value = options[key] || DeskApi.instance_variable_get(:"@#{key}")
+        instance_variable_set(:"@#{key}", value)
+      end
+    end
 
-  # Perform an HTTP POST request
-  def post(path, params = {})
-    request(:post, path, params)
-  end
+    # Perform an http request
+    #
+    # @param path [String] the url path to the resource
+    # @param params [Hash] optional additional url params
+    # @yield [Faraday::Response] for further request customizations.
+    # @return [Faraday::Response]
+    %w(get head delete post patch).each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(path, params = {}, &block)
+          request(:#{method}, path, params, &block)
+        end
+      RUBY
+    end
 
-  # Perform an HTTP PATCH request
-  def patch(path, params = {})
-    request(:patch, path, params)
-  end
+    # Returns a new resource for the given path
+    #
+    # @param path [String] the url path to the resource
+    # @return [DeskApi::Resource]
+    def by_url(path)
+      DeskApi::Resource.new(self, DeskApi::Resource.build_self_link(path))
+    end
 
-  # allow lookup by url
-  def by_url(url)
-    DeskApi::Resource.new(self, DeskApi::Resource.build_self_link(url))
-  end
+    private
 
-private
-  # If the method is missing create a resource
-  def method_missing(method, params = {}, &block)
-    DeskApi::Resource.new(self, DeskApi::Resource.build_self_link("/api/v2/#{method}")).tap do |res|
-      res.query_params = params
+    # Returns a new resource based on the method you're trying to load:
+    #
+    # @example request cases
+    #   my_cases = client.cases # GET '/api/v2/cases'
+    # @param method [Symbol] the method called
+    # @param params [Hash] additional query params
+    # @yield [DeskApi::Resource]
+    # @return [DeskApi::Resource]
+    def method_missing(method, params = {})
+      definition = DeskApi::Resource.build_self_link("/api/v2/#{method}")
+      DeskApi::Resource.new(self, definition).tap do |res|
+        res.query_params = params
+        yield res if block_given?
+      end
     end
-  end
 
-  def request(method, path, params = {})
-    connection.send(method, path, params)
-  rescue Faraday::Error::ClientError
-    raise DeskApi::Error::ClientError
-  rescue JSON::ParserError
-    raise DeskApi::Error::ParserError
-  end
+    # Hands off the request to Faraday for further processing
+    #
+    # @param method [Symbol] the http method to call
+    # @param path [String] the url path to the resource
+    # @param params [Hash] optional additional url params
+    # @yield [Faraday::Response] for further request customizations.
+    # @return [Faraday::Response]
+    # @raises [DeskApi::Error::ClientError]
+    # @raises [DeskApi::Error::ParserError]
+    def request(method, path, params = {}, &block)
+      connection.send(method, path, params, &block)
+    rescue Faraday::Error::ClientError
+      raise DeskApi::Error::ClientError
+    rescue JSON::ParserError
+      raise DeskApi::Error::ParserError
+    end
 
-  def connection
-    @connection ||= Faraday.new endpoint, connection_options, &middleware
+    # Builds and/or returns the Faraday client.
+    # @returns [Faraday::Connection]
+    def connection
+      @connection ||= Faraday.new endpoint, connection_options, &middleware
+    end
   end
 end