orchestrate 0.5.1 → 0.6.0

data/lib/orchestrate/client.rb

@@ -3,359 +3,346 @@ require 'faraday_middleware'
 
 module Orchestrate
 
-  # ==== Ruby Client for the Orchestrate REST *API*.
-  #
-  # The primary entry point is the #send_request method, which generates a
-  # Request, and returns the Response to the caller.
-  #
   class Client
 
-    # Orchestrate::Configuration instance for the client.  If not explicitly
-    # provided during initialization, will default to Orchestrate.config
-    attr_accessor :config
-
-    # The Faraday HTTP "connection" for the client.
-    attr_accessor :http
-
-    # Initialize and return a new Client instance. Optionally, configure
-    # options for the instance by passing a Configuration object. If no
-    # custom configuration is provided, the configuration options from
-    # Orchestrate.config will be used.
-    def initialize(config = Orchestrate.config)
-      @config = config
-
-      @http = Faraday.new(config.base_url) do |faraday|
-        if config.faraday.respond_to?(:call)
-          config.faraday.call(faraday)
-        else
-          faraday.adapter Faraday.default_adapter
-        end
+    # @return [String] The API key provided
+    attr_reader :api_key
+
+    # @return [Faraday::Connection] The Faraday HTTP connection.
+    attr_reader :http
+
+    # @return [Proc] The block used to configure faraday.
+    attr_reader :faraday_configuration
+
+    # Instantiate a new Client for an Orchestrate application.
+    # @param api_key [#to_s] The API Key for your Orchestrate application.
+    # @yieldparam [Faraday::Connection] The setup for the faraday connection.
+    # @return Orchestrate::Client
+    # @todo api_key -> app_url, parse api_key from auth section of url
+    def initialize(api_key, &block)
+      @api_key = api_key
+      @faraday_configuration = block
+      @http = Faraday.new("https://api.orchestrate.io") do |faraday|
+        block = lambda{|f| f.adapter Faraday.default_adapter } unless block
+        block.call faraday
 
         # faraday seems to want you do specify these twice.
-        faraday.request :basic_auth, config.api_key, ''
-        faraday.basic_auth config.api_key, ''
+        faraday.request :basic_auth, api_key, ''
+        faraday.basic_auth api_key, ''
 
         # parses JSON responses
         faraday.response :json, :content_type => /\bjson$/
       end
     end
 
-    # -------------------------------------------------------------------------
-    #  collection
-
-    # call-seq:
-    #   client.list(collection_name, parameters = {})   -> response
-    #
-    # Performes a List query against the given collection.  Results are sorted
-    # lexicographically by key name.
-    #
-    # +collection_name+:: A String or Symbol representing the name of the collection.
-    # +parameters+:: a Hash object containing query parameters:
-    # - +:limit+   - integer, number of results to return.  Defaults to 10, Max 100.
-    # - +:start+   - string, start key of query range, including value.
-    # - +:after+   - string, start key of query range, excluding value.
-    # - +:before+  - string, end key of query range, excluding value.
-    # - +:end+     - string, end key of query range, including value.
-    #
-    # Note, you cannot provide *both* 'start' and 'after', or 'before' and 'end'
-    #
-    def list(collection, options={})
-      Orchestrate::Helpers.range_keys!('key', options)
-      send_request :get, [collection], { query: options }
+    # Tests authentication with Orchestrate.
+    # @return Orchestrate::API::Response
+    # @raise Orchestrate::API::Unauthorized if the client could not authenticate.
+    def ping
+      send_request :get, []
     end
 
-    # call-seq:
-    #   client.list(collection_name, query, parameters = {})  -> response
-    #
-    # Performs a Search query against the given collection.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +query+:: a String containing a Lucene query
-    # +parameters+:: a Hash object containing additional parameters:
-    # - +limit+:  - integer, number of results to return.  Defaults to 10, Max 100.
-    # - +offset+: - ingeger, the starting position of the results.  Defaults to 0.
-    #
-    def search(collection, query, parameters={})
-      send_request :get, [collection], { query: parameters.merge({query: query})}
+    # @!group Collections
+
+    # [Search the items in
+    # a collection](http://orchestrate.io/docs/api/#search) using a Lucene
+    # Query Syntax.
+    # @param collection [#to_s] The name of the collection
+    # @param query [String] The [Lucene Query String][lucene] to query the collection with.
+    #   [lucene]: http://lucene.apache.org/core/4_3_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#Overview
+    # @param options [Hash] Parameters for the query
+    # @option options [Integer] :limit (10) The number of results to return. Maximum 100.
+    # @option options [Integer] :offset (0) The starting position of the results.
+    # @return Orchestrate::API::CollectionResponse
+    # @raise Orchestrate::API::InvalidSearchParam The :limit/:offset values are not valid.
+    # @raise Orchestrate::API::SearchQueryMalformed if query isn't a valid Lucene query.
+    def search(collection, query, options={})
+      send_request :get, [collection], { query: options.merge({query: query}),
+                                         response: API::CollectionResponse }
     end
 
-    # call-seq:
-    #   client.delete_collection(collection_name) -> response
-    #
-    # Deletes the given collection.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    #
+    # [Deletes an entire collection](http://orchestrate.io/docs/api/#collections/delete)
+    # @param collection [#to_s] The name of the collection
+    # @return Orchestrate::API::Response
+    # @note The Orchestrate API will return succesfully regardless of if the collection exists or not.
     def delete_collection(collection)
       send_request :delete, [collection], { query: {force:true} }
     end
 
-    #  -------------------------------------------------------------------------
-    #  Key/Value
-
-    # call-seq:
-    #   client.get(collection_name, key)              -> response
-    #   client.get(collection_name, key, ref)         -> response
-    #
-    # Retreieves a value assigned to a key.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +ref+:: if given, returns the value for the key at the specified ref.  If omitted, returns the latest value for the key.
-    #
+    # @!endgroup
+    # @!group Key/Value
+
+    # [Retrieves the value assigned to a key](http://orchestrate.io/docs/api/#key/value/get).
+    # If a `ref` parameter is provided, [retrieves a historical value for the
+    # key](http://orchestrate.io/docs/api/#refs/get14)
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param ref [#to_s] The opaque version identifier of the ref to return, if a historical value is desired.
+    # @return Orchestrate::API::ItemResponse
+    # @raise Orchestrate::API::NotFound If the key or ref doesn't exist.
+    # @raise Orchestrate::API::MalformedRef If the ref provided is not a valid ref.
     def get(collection, key, ref=nil)
-      if ref
-        send_request :get, [collection, key, 'refs', ref]
-      else
-        send_request :get, [collection, key]
-      end
+      path = [collection, key]
+      path.concat(['refs', ref]) if ref
+      send_request :get, path, { response: API::ItemResponse }
     end
 
-    # call-seq:
-    #   client.put(collection_name, key, body)            -> response
-    #   client.put(collection_name, key, body, condition) -> response
-    #
-    # Creates or Updates the value at the specified key.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +body+:: a Hash object representing the value for the key.
-    # +condition+::
-    # - +nil+ - the value for the specified key will be updated regardless.
-    # - String - used as 'If-Match'.  The value will only be updated if the Key's current Value's Ref matches the given condition.
-    # - false - used as 'If-None-Match'.  The value will only be created for the key if the key currently has no value.
-    #
+    # [List historical refs for values of a key](http://orchestrate.io/docs/api/#refs/list15).
+    # Results are time-ordered newest-to-oldest and paginated.
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param options [Hash] Parameters for the query.
+    # @option options [Integer] :limit (10) The number of results to return. Maximum 100.
+    # @option options [Integer] :offset (0) The starting position of the results.
+    # @option options [true, false] :values (false) Whether to return the value
+    #   for each ref.  Refs with no content (for example, deleted with `#delete`) will not have
+    #   a value, but marked with a `'tombstone' => true` key.
+    # @return Orchestrate::API::CollectionResponse
+    # @raise Orchestrate::API::NotFound If there are no values for the provided key/collection.
+    # @raise Orchestrate::API::InvalidSearchParam The :limit/:offset values are not valid.
+    # @raise Orchestrate::API::MalformedRef If the ref provided is not a valid ref.
+    def list_refs(collection, key, options={})
+      send_request :get, [collection, key, :refs], { query: options, response: API::CollectionResponse }
+    end
+
+    # [Updates the value associated with
+    # a key](http://orchestrate.io/docs/api/#key/value/put-\(create/update\)).
+    # If the key does not currently have a value, will create the value.
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param body [#to_json] The value for the key.
+    # @param condition [String, false, nil] Conditions for setting the value. 
+    #   If `String`, value used as `If-Match`, value will only be updated if key's current value's ref matches.
+    #   If `false`, uses `If-None-Match` the value will only be set if there is no existent value for the key.
+    #   If `nil` (default), value is set regardless.
+    # @return Orchestrate::API::ItemResponse
+    # @raise Orchestrate::API::BadRequest the body is not valid JSON.
+    # @raise Orchestrate::API::IndexingConflict One of the value's keys
+    #   contains a value of a different type than the schema that exists for
+    #   the collection.
+    # @see Orchestrate::API::IndexingConflict
+    # @raise Orchestrate::API::VersionMismatch A ref was provided, but it does not match the ref for the current value.
+    # @raise Orchestrate::API::AlreadyPresent the `false` condition was given, but a value already exists for this collection/key combo.
     def put(collection, key, body, condition=nil)
       headers={}
       if condition.is_a?(String)
-        headers['If-Match'] = format_ref(condition)
+        headers['If-Match'] = API::Helpers.format_ref(condition)
       elsif condition == false
         headers['If-None-Match'] = '*'
       end
-      send_request :put, [collection, key], { body: body, headers: headers }
+      send_request :put, [collection, key], { body: body, headers: headers, response: API::ItemResponse }
     end
     alias :put_if_unmodified :put
 
-    #  call-seq:
-    #     client.put_if_absent(collection_name, key, body)    -> response
-    #
-    # Will create the value at the specified key only if there is no existing value for the specified key.
-    #
+    # [Creates the value for a key if none
+    # exists](http://orchestrate.io/docs/api/#key/value/put-\(create/update\)).
+    # @see #put
     def put_if_absent(collection, key, body)
       put collection, key, body, false
     end
 
-    # call-seq:
-    #   client.delete(collection_name, key)      -> response
-    #   client.delete(collection_name, key, ref) -> response
-    #
-    # Deletes the value of the specified key.  Historical values for given refs are still available.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +ref+:: if provided, used as 'If-Match', will only delete the key if the current value is the provided ref.
-    #
+    # [Sets the current value of a key to a null
+    # object](http://orchestrate.io/docs/api/#key/value/delete11).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param ref [#to_s] If specified, deletes the ref only if the current value's ref matches.
+    # @return Orchestrate::API::Response
+    # @raise Orchestrate::API::VersionMismatch if the provided ref is not the ref for the current value.
+    # @note previous versions of the values at this key are still available via #list_refs and #get.
     def delete(collection, key, ref=nil)
       headers = {}
-      headers['If-Match'] = format_ref(ref) if ref
+      headers['If-Match'] = API::Helpers.format_ref(ref) if ref
       send_request :delete, [collection, key], { headers: headers }
     end
 
-    # call-seq:
-    #   client.purge(collection_name, key) -> response
-    #
-    # Deletes the value for the specified key as well as all historical values.  Cannot be undone.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    #
+    # [Purges the current value and ref history associated with the
+    # key](http://orchestrate.io/docs/api/#key/value/delete11).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @return Orchestrate::API::Response
+    # @todo take an optional ref for If-Match
     def purge(collection, key)
       send_request :delete, [collection, key], { query: { purge: true } }
     end
 
-    # -------------------------------------------------------------------------
-    #  Events
-
-    # call-seq:
-    #   client.get_event(collection_name, key, event_type, timestamp, ordinal) -> response
-    #
-    # Gets the event for the specified arguments.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +event_type+:: a String or Symbol representing the category for the event.
-    # +timestamp+:: an Integer or String representing a time.
-    # - Integers are Milliseconds since Unix Epoch.
-    # - Strings must be formatted as per http://orchestrate.io/docs/api/#events/timestamps
-    # - A future version will support ruby Time objects.
-    # +ordinal+:: an Integer representing the order of the event for this timestamp.
-    #
+    # [List the KeyValue items in a collection](http://orchestrate.io/docs/api/#key/value/list).
+    # Results are sorted results lexicographically by key name and paginated.
+    # @param collection [#to_s] The name of the collection
+    # @param options [Hash] Parameters for the query
+    # @option options [Integer] :limit (10) The number of results to return. Maximum 100.
+    # @option options [String] :start The inclusive start key of the query range.
+    # @option options [String] :after The exclusive start key of the query range.
+    # @option options [String] :before The exclusive end key of the query range.
+    # @option options [String] :end The inclusive end key of the query range.
+    # @note The Orchestrate API may return an error if you include both the
+    #   :start/:after or :before/:end keys.  The client will not stop you from doing this.
+    # @note To include all keys in a collection, do not include any :start/:after/:before/:end parameters.
+    # @return Orchestrate::API::CollectionResponse
+    # @raise Orchestrate::API::InvalidSearchParam The :limit value is not valid.
+    def list(collection, options={})
+      API::Helpers.range_keys!('key', options)
+      send_request :get, [collection], { query: options, response: API::CollectionResponse }
+    end
+
+    # @!endgroup
+    # @!group Events
+
+    # [Retrieves an individual event](http://orchestrate.io/docs/api/#events/get19).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param event_type [#to_s] The category for the event.
+    # @param timestamp [Time, Date, Integer, String] The timestamp for the event.
+    #   If a String, must match the [Timestamp specification](http://orchestrate.io/docs/api/#events/timestamps)
+    #   and include the milliseconds portion.
+    # @param ordinal [Integer, #to_s] The ordinal for the event in the given timestamp.
+    # @return Orchestrate::API::ItemResponse
+    # @raise Orchestrate::API::NotFound If the requested event doesn't exist.
     def get_event(collection, key, event_type, timestamp, ordinal)
-      send_request :get, [collection, key, 'events', event_type, timestamp, ordinal]
+      timestamp = API::Helpers.timestamp(timestamp)
+      path = [collection, key, 'events', event_type, timestamp, ordinal]
+      send_request :get, path, { response: API::ItemResponse }
     end
 
-    # call-seq:
-    #   client.post_event(collection_name, key, event_type) -> response
-    #   client.post_event(collection_name, key, event_type, timestamp) -> response
-    #
-    # Creates an event.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +event_type+:: a String or Symbol representing the category for the event.
-    # +body+:: a Hash object representing the value for the event.
-    # +timestamp+:: an Integer or String representing a time.
-    # - nil - Timestamp value will be created by Orchestrate.
-    # - Integers are Milliseconds since Unix Epoch.
-    # - Strings must be formatted as per http://orchestrate.io/docs/api/#events/timestamps
-    # - A future version will support ruby Time objects.
-    #
+    # [Creates an event](http://orchestrate.io/docs/api/#events/post-\(create\)).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param event_type [#to_s] The category for the event.
+    # @param body [#to_json] The value for the event.
+    # @param timestamp [Time, Date, Integer, String, nil] The timestamp for the event.
+    #   If omitted, the timestamp is created by Orchestrate.
+    #   If a String, must match the [Timestamp specification](http://orchestrate.io/docs/api/#events/timestamps).
+    # @return Orchestrate::API::ItemResponse
+    # @raise Orchestrate::API::BadRequest If the body is not valid JSON.
     def post_event(collection, key, event_type, body, timestamp=nil)
+      timestamp = API::Helpers.timestamp(timestamp)
       path = [collection, key, 'events', event_type, timestamp].compact
-      send_request :post, path, { body: body }
+      send_request :post, path, { body: body, response: API::ItemResponse }
     end
 
-    # call-seq:
-    #   client.put_event(collection_name, key, event_type, timestamp, ordinal, body) -> response
-    #   client.put_event(collection_name, key, event_type, timestamp, ordinal, body, ref) -> response
-    #
-    # Puts the event for the specified arguments.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +event_type+:: a String or Symbol representing the category for the event.
-    # +timestamp+:: an Integer or String representing a time.
-    # - Integers are Milliseconds since Unix Epoch.
-    # - Strings must be formatted as per http://orchestrate.io/docs/api/#events/timestamps
-    # - A future version will support ruby Time objects.
-    # +ordinal+:: an Integer representing the order of the event for this timestamp.
-    # +body+:: a Hash object representing the value for the event.
-    # +ref+::
-    # - +nil+ - The event will update regardless.
-    # - String - used as 'If-Match'.  The event will only update if the event's current value matches this ref.
-    #
+    # [Updates an existing event](http://orchestrate.io/docs/api/#events/put-\(update\)).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param event_type [#to_s] The category for the event.
+    # @param timestamp [Time, Date, Integer, String, nil] The timestamp for the event.
+    #   If a String, must match the [Timestamp specification](http://orchestrate.io/docs/api/#events/timestamps)
+    #   and include the milliseconds portion.
+    # @param ordinal [Integer, #to_s] The ordinal for the event in the given timestamp.
+    # @param body [#to_json] The value for the event.
+    # @param ref [nil, #to_s] If provided, used as `If-Match`, and event will
+    #   only update if its current value has the provided ref.  If omitted,
+    #   updates the event regardless.
+    # @return Orchestrate::API::ItemResponse
+    # @raise Orchestrate::API::NotFound The specified event doesn't exist.
+    # @raise Orchestrate::API::BadRequest If the body is not valid JSON.
+    # @raise Orchestrate::API::VersionMismatch The event's current value has a ref that does not match the provided ref.
+    # @raise Orchestrate::API::MalformedRef If the ref provided is not a valid ref.
     def put_event(collection, key, event_type, timestamp, ordinal, body, ref=nil)
+      timestamp = API::Helpers.timestamp(timestamp)
       path = [collection, key, 'events', event_type, timestamp, ordinal]
       headers = {}
-      headers['If-Match'] = format_ref(ref) if ref
-      send_request :put, path, { body: body, headers: headers }
+      headers['If-Match'] = API::Helpers.format_ref(ref) if ref
+      send_request :put, path, { body: body, headers: headers, response: API::ItemResponse }
     end
 
-    # call-seq:
-    #   client.purge_event(collection, key, event_type, timestamp, ordinal) -> response
-    #   client.purge_event(collection, key, event_type, timestamp, ordinal, ref) -> response
-    #
-    # Deletes the event for the specified arguments.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +event_type+:: a String or Symbol representing the category for the event.
-    # +timestamp+:: an Integer or String representing a time.
-    # - Integers are Milliseconds since Unix Epoch.
-    # - Strings must be formatted as per http://orchestrate.io/docs/api/#events/timestamps
-    # - A future version will support ruby Time objects.
-    # +ordinal+:: an Integer representing the order of the event for this timestamp.
-    # +ref+::
-    # - +nil+ - The event will be deleted regardless.
-    # - String - used as 'If-Match'.  The event will only be deleted if the event's current value matches this ref.
-    #
+    # [Deletes an existing event](http://orchestrate.io/docs/api/#events/delete22).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param event_type [#to_s] The category for the event.
+    # @param timestamp [Time, Date, Integer, String, nil] The timestamp for the event.
+    #   If a String, must match the [Timestamp specification](http://orchestrate.io/docs/api/#events/timestamps)
+    #   and include the milliseconds portion.
+    # @param ordinal [Integer, #to_s] The ordinal for the event in the given timestamp.
+    # @param ref [nil, #to_s] If provided, used as `If-Match`, and event will
+    #   only update if its current value has the provided ref.  If omitted,
+    #   updates the event regardless.
+    # @return Orchestrate::API::Response
+    # @raise Orchestrate::API::VersionMismatch The event's current value has a ref that does not match the provided ref.
+    # @raise Orchestrate::API::MalformedRef If the ref provided is not a valid ref.
     def purge_event(collection, key, event_type, timestamp, ordinal, ref=nil)
+      timestamp = API::Helpers.timestamp(timestamp)
       path = [collection, key, 'events', event_type, timestamp, ordinal]
       headers = {}
-      headers['If-Match'] = format_ref(ref) if ref
+      headers['If-Match'] = API::Helpers.format_ref(ref) if ref
       send_request :delete, path, { query: { purge: true }, headers: headers }
     end
 
-    # call-seq:
-    #   client.list_events(collection_name, key, event_type) -> response
-    #   client.list_events(collection_name, key, event_type, parameters = {}) -> response
-    #
-    # Puts the event for the specified arguments.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +event_type+:: a String or Symbol representing the category for the event.
-    # +parameters+::
-    # - +:limit+   - integer, number of results to return.  Defaults to 10, Max 100.
-    # - +:start+   - Integer/String representing the inclusive start to a range.
-    # - +:after+   - Integer/String representing the exclusive start to a range.
-    # - +:before+  - Integer/String representing the exclusive end to a range.
-    # - +:end+     - Integer/String representing the inclusive end to a range.
-    #
-    # Range parameters are formatted as ":timestamp/:ordinal":
-    # +timestamp+:: an Integer or String representing a time.
-    # - Integers are Milliseconds since Unix Epoch.
-    # - Strings must be formatted as per http://orchestrate.io/docs/api/#events/timestamps
-    # - A future version will support ruby Time objects.
-    # +ordinal+:: is optional.
-    #
-    def list_events(collection, key, event_type, parameters={})
-      Orchestrate::Helpers.range_keys!('event', parameters)
-      send_request :get, [collection, key, 'events', event_type], { query: parameters }
+    # [Lists events associated with a key](http://orchestrate.io/docs/api/#events/list23).
+    # Results are time-ordered in reverse-chronological order, and paginated.
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param event_type [#to_s] The category for the event.
+    # @param options [Hash] The parameters for the query.
+    # @option options [Integer] :limit (10) The number of results to return.  Default 100.
+    # @option options [Date, Time, String, Integer] :start The inclusive start of the range.
+    # @option options [Date, Time, String, Integer] :after The exclusive start of the range.
+    # @option options [Date, Time, String, Integer] :before The exclusive end of the range.
+    # @option options [Date, Time, String, Integer] :end The inclusive end of the range.
+    # @return Orchestrate::API::CollectionResponse
+    # @raise Orchestrate::API::NotFound If the provided collection/key doesn't exist.
+    def list_events(collection, key, event_type, options={})
+      (options.keys & [:start, :after, :before, :end]).each do |param|
+        options[param] = API::Helpers.timestamp(options[param])
+      end
+      API::Helpers.range_keys!('event', options)
+      path = [collection, key, 'events', event_type]
+      send_request :get, path, { query: options, response: API::CollectionResponse }
     end
 
-    # -------------------------------------------------------------------------
-    #  Graph
-
-    # call-seq:
-    #   client.get_relations(collection_name, key, *kinds) -> response
-    #
-    # Returns the relation's collection, key and ref values.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +kinds+:: one or more String or Symbol values representing the relations and depth to walk.
-    #
+    # @!endgroup
+    # @!group Graphs / Relations
+
+    # [Retrieves a relation's associated objects](http://orchestrate.io/docs/api/#graph/get26).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param kinds [#to_s] The relationship kinds and depth to query.
+    # @example Retrieves the friend's of John's family
+    #   client.get_relations(:users, 'john', :family, :friends)
+    # @example If the relation facets exist in an array, use:
+    #   relations = [:family, :friends]
+    #   client.get_relations(:users, 'john', *relations)
+    # @return Orchestrate::API::CollectionResponse
+    # @raise Orchestrate::API::NotFound If the given collection/key doesn't exist.
     def get_relations(collection, key, *kinds)
       path = [collection, key, 'relations'].concat(kinds)
-      send_request :get, path
+      send_request :get, path, {response: API::CollectionResponse}
     end
 
-    # call-seq:
-    #   client.put_relation(collection_name, key, kind, to_collection_name, to_key) -> response
-    #
-    # Stores a relationship between two Key/Value items.  They do not need to be in the same collection.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +kind+:: a String or Symbol value representing the relation type.
-    # +to_collection_name+:: a String or Symbol representing the name of the collection the related item belongs.
-    # +to_key+:: a String or Symbol representing the key for the related item.
-    #
+    # [Creates a relationship between two Key/Value objects](http://orchestrate.io/docs/api/#graph/put).
+    # Relations can span collections.
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param kind [#to_s] The kind of relationship to create.
+    # @param to_collection [#to_s] The name of the collection to relate to.
+    # @param to_key [#to_s] The name of the key to relate to.
+    # @return Orchestrate::API::Response
+    # @raise Orchestrate::API::NotFound If either end of the relation doesn't exist.
     def put_relation(collection, key, kind, to_collection, to_key)
       send_request :put, [collection, key, 'relation', kind, to_collection, to_key]
     end
 
-    # call-seq:
-    #   client.delete_relation(collection_name, key, kind, to_collection, to_key) -> response
-    #
-    # Deletes a relationship between two Key/Value items.
-    #
-    # +collection_name+:: a String or Symbol representing the name of the collection.
-    # +key+:: a String or Symbol representing the key for the value.
-    # +kind+:: a String or Symbol value representing the relation type.
-    # +to_collection_name+:: a String or Symbol representing the name of the collection the related item belongs.
-    # +to_key+:: a String or Symbol representing the key for the related item.
-    #
+    # [Deletes a relationship between two objects](http://orchestrate.io/docs/api/#graph/delete28).
+    # @param collection [#to_s] The name of the collection.
+    # @param key [#to_s] The name of the key.
+    # @param kind [#to_s] The kind of relationship to delete.
+    # @param to_collection [#to_s] The name of the collection to relate to.
+    # @param to_key [#to_s] The name of the key to relate to.
+    # @return Orchestrate::API::Response
     def delete_relation(collection, key, kind, to_collection, to_key)
       path = [collection, key, 'relation', kind, to_collection, to_key]
       send_request :delete, path, { query: {purge: true} }
     end
 
-    # call-seq:
-    #   client.in_parallel {|responses| block } -> Hash
-    #
-    # Performs any requests generated inside the block in parallel.  If the
-    # client isn't using a Faraday adapter that supports parallelization, will
-    # output a warning to STDERR.
-    #
-    # Example:
+    # @!endgroup
+
+    # Performs requests in parallel.  Requires using a Faraday adapter that supports parallel requests.
+    # @yieldparam accumulator [Hash] A place to store the results of the parallel responses.
+    # @example Performing three requests at once
     #   responses = client.in_parallel do |r|
     #     r[:some_items] = client.list(:site_globals)
     #     r[:user] = client.get(:users, current_user_key)
     #     r[:user_feed] = client.list_events(:users, current_user_key, :notices)
     #   end
-    #
+    # @see README See the Readme for more examples.
     def in_parallel(&block)
       accumulator = {}
       http.in_parallel do
@@ -364,47 +351,48 @@ module Orchestrate
       accumulator
     end
 
-    # call-seq:
-    #   client.send_request(method, url, opts={}) -> response
-    #
-    # Performs the HTTP request against the API and returns a Faraday::Response
-    #
-    # +method+ - the HTTP method, one of [ :get, :post, :put, :delete ]
-    # +url+ - an Array of segments to be joined with '/'
-    # +opts+
-    # - +:query+ - a Hash for the request query string
-    # - +:body+ - a Hash for the :put or :post request body
-    # - +:headers+ - a Hash the request headers
-    #
-    def send_request(method, url, opts={})
-      url = "/v0/#{url.join('/')}"
-      query_string = opts.fetch(:query, {})
-      body = opts.fetch(:body, '')
-      headers = opts.fetch(:headers, {})
+    # Performs an HTTP request against the Orchestrate API
+    # @param method [Symbol] The HTTP method - :get, :post, :put, :delete
+    # @param path [Array<#to_s>] Path segments for the request's URI.  Prepended by 'v0'.
+    # @param options [Hash] extra parameters
+    # @option options [Hash] :query ({}) Query String parameters.
+    # @option options [#to_json] :body ('') The request body.
+    # @option options [Hash] :headers ({}) Extra request headers.
+    # @option options [Class] :response (Orchestrate::API::Response) A subclass of Orchestrate::API::Response to instantiate and return
+    # @return API::Response
+    # @raise [Orchestrate::API::RequestError, Orchestrate::API::ServiceError] see http://orchestrate.io/docs/api/#errors
+    def send_request(method, path, options={})
+      path = ['/v0'].concat(path).join('/')
+      query_string = options.fetch(:query, {})
+      body = options.fetch(:body, '')
+      headers = options.fetch(:headers, {})
       headers['User-Agent'] = "ruby/orchestrate/#{Orchestrate::VERSION}"
       headers['Accept'] = 'application/json' if method == :get
 
-      http.send(method) do |request|
-        config.logger.debug "Performing #{method.to_s.upcase} request to \"#{url}\""
-        request.url url, query_string
+      response = http.send(method) do |request|
+        request.url path, query_string
         if [:put, :post].include?(method)
           headers['Content-Type'] = 'application/json'
           request.body = body.to_json
         end
         headers.each {|header, value| request[header] = value }
       end
-    end
-
-    # ------------------------------------------------------------------------
 
-    private
-
-      # Formats the provided 'ref' to be quoted per API specification.  If
-      # already quoted, does not add additional quotes.
-      def format_ref(ref)
-        "\"#{ref.gsub(/"/,'')}\""
+      if ! response.success?
+        err_type = API::ERRORS.find do |err|
+          err.status == response.status && err.code == response.body['code']
+        end
+        if err_type
+          raise err_type.new(response)
+        elsif response.status >= 500
+          raise API::ServiceError.new(response)
+        elsif response.status >= 400
+          raise API::RequestError.new(response)
+        end
       end
-
+      response_class = options.fetch(:response, API::Response)
+      response_class.new(response, self)
+    end
   end
 
 end