orchestrate 0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d745f6432de35d38a03090bad7e072c5050f2660
+  data.tar.gz: b48814208a0b00a4c4d80bad1ea1e0a7d9c3e51c
+SHA512:
+  metadata.gz: 99d1b6e4fffed62524458cd0862fc71d0d6f3d6cdc2187ce8882007159bbddfda38cac003f304ffb53e75fa8fceda1a8fe389963c6ff50448db84f796c112e16
+  data.tar.gz: c5f59656dc41f5b4eab6f9840a838b69938e20ac50d9d3c8cf44d0e337a946de98e4290260dd2e64b19c43b56351a86e0dc59515035f6554f2673e2d555a9419

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.lock
+*.rbc
+*.log
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.1.1
+  - 2.1.0
+  - 2.0.0
+  - 1.9.3
+before_install: gem install bundler -v 1.6.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in orchestrate-rails.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 jimcar
+
+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.

data/README.md

@@ -0,0 +1,115 @@
+Orchestrate API for Ruby
+========================
+[![Build Status](https://travis-ci.org/orchestrate-io/orchestrate-ruby.png?branch=master)](https://travis-ci.org/orchestrate-io/orchestrate-ruby)
+
+Ruby client interface for the [Orchestrate.io](http://orchestrate.io) REST API.
+
+[rDoc Documentation](http://rdoc.info/github/orchestrate-io/orchestrate-ruby/master/frames)
+
+## Getting Started
+
+Provide your API key:
+
+``` ruby
+Orchestrate::Configuration.api_key = '8ce391a...'
+```
+
+Create a client:
+
+``` ruby
+client = Orchestrate::Client.new
+```
+
+and start making requests:
+
+``` ruby
+client.list(:my_collection)
+```
+
+## Swapping out the HTTP backend
+
+This gem uses [Faraday][] for its HTTP needs -- and Faraday allows you to change the underlying HTTP client used.  It defaults to `Net::HTTP` but if you wanted to use [Typhoeus][] or [EventMachine HTTP][em-http], doing so would be easy.  Alternate Faraday backends enable using callbacks or parallel request support.
+
+In your Orchestrate configuration, simply provide a `faraday` key with a block that will be called with the `Faraday::Connection` object.  You may decorate it with middleware or change the adapter as described in the Faraday README.  Examples are below.
+
+You may use Faraday's `test` adapter to stub out calls to the Orchestrate API in your tests.  See `tests/test_helper.rb` and the tests in `tests/orchestrate/api/*_test.rb` for examples.
+
+[Faraday]: https://github.com/lostisland/faraday/
+[Typhoeus]: https://github.com/typhoeus/typhoeus#readme
+[em-http]: https://github.com/igrigorik/em-http-request#readme
+
+### Parallel HTTP requests
+
+If you're using a Faraday backend that enables parallelization, such as Typhoeus, EM-HTTP-Request, or EM-Synchrony you can use `Orchestrate::Client#in_parallel` to fire off multiple requests at once.  If your Faraday backend does not support this, the method will still work as expected, but Faraday will output a warning to STDERR and the requests will be performed in series.
+
+``` ruby
+client = Orchestrate::Client.new
+
+responses = client.in_parallel do |r|
+  r[:list] = client.list(:my_collection)
+  r[:user] = client.get(:users, current_user_id)
+  r[:user_events] = client.list_events(:users, current_user_id, :notices)
+end
+# will return when all requests have completed
+
+responses[:user] = #<Faraday::Response:0x00...>
+```
+
+### Callback Support
+
+If you're using a Faraday backend that enables callbacks, such as EM-HTTP-Request or EM-Synchrony, you may use the callback interface to designate actions to perform when the request completes.
+
+``` ruby
+client = Orchestrate::Client.new
+response = client.list(:my_collection)
+response.finished? # false
+response.on_complete do
+  # do stuff with the response as normal
+end
+```
+
+If the Faraday backend adapter does not support callbacks, the block provided will be executed when `Orchestrate::Client#on_complete` is called.
+
+
+### Using with Typhoeus
+
+Typhoeus is backed by libcurl and enables parallelization.
+
+``` ruby
+require 'typhoeus'
+require 'typhoeus/adapters/faraday'
+
+Orchestrate.configure do |config|
+  config.faraday = {|f| f.adapter :typhoeus }
+  config.api_key = "my_api_key"
+end
+```
+
+### Using with EM-HTTP-Request
+
+EM-HTTP-Request is an HTTP client for Event Machine.  It enables callback support and parallelization.
+
+
+``` ruby
+require 'em-http-request'
+
+Orchestrate.configure do |config|
+  config.faraday = {|f| f.adapter :em_http }
+  config.api_key = "my_api_key"
+end
+```
+
+### Using with EM-Syncrony
+
+EM-Synchrony is a collection of utility classes for EventMachine to help untangle evented code.  It enables parallelization.
+
+``` ruby
+require 'em-synchrony'
+
+Orchestrate.configure do |config|
+  config.faraday = {|f| f.adapter :em_synchrony }
+  config.api_key = "my_api_key"
+end
+```
+
+

data/Rakefile

@@ -0,0 +1,20 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rdoc/task"
+
+task default: :test
+
+Rake::TestTask.new do |test|
+  test.libs << "test"
+  test.test_files = FileList["test/**/*_test.rb"]
+  test.verbose = true
+end
+
+Rake::RDocTask.new(rdoc: "doc", clobber_rdoc: "doc:clean", rerdoc: "doc:force") do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.title = "Orchestrate API Documentation"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+  rdoc.rdoc_dir = "doc"
+end
+

data/lib/orchestrate.rb

@@ -0,0 +1,46 @@
+require "orchestrate/api"
+require "orchestrate/client"
+require "orchestrate/configuration"
+require "orchestrate/helpers"
+require "orchestrate/version"
+
+#
+# A library for supporting connections to the \Orchestrate API.
+#
+module Orchestrate
+
+  # Configuration ------------------------------------------------------------
+
+  class << self
+
+    #
+    # An instance of Configuration containing the current library
+    # configuration options.
+    #
+    attr_accessor :config
+
+    #
+    # Lazily initialize and return the Configuration instance.
+    #
+    def config # :nodoc:
+      @config ||= Configuration.new
+    end
+
+    #
+    # Configure the Orchestrate library. This method should be called during
+    # application or script initialization. At a bare minimum, the Orchestrate
+    # library will require that an API key is provided.
+    #
+    # ==== Example
+    #
+    #   Orchestrate.configure do |config|
+    #     config.api_key = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    #   end
+    #
+    def configure
+      yield config
+    end
+
+  end
+
+end

data/lib/orchestrate/api.rb

@@ -0,0 +1,15 @@
+require "orchestrate"
+require "orchestrate/api/extensions"
+
+module Orchestrate
+
+  #
+  # Ruby gem +orchestrate-api+ provides an interface to the
+  # [Orchestrate](http://orchestrate.io) API.
+  #
+  # The Client class is used to setup the client and make HTTP requests.
+  #
+  module API
+  end
+
+end

data/lib/orchestrate/api/errors.rb

@@ -0,0 +1,57 @@
+module Orchestrate::API
+
+  # Not used. But it does contain nice summary of orchestrate.io api errors.
+  #
+  module Error
+    def errors
+      @@errors ||= [
+        { :status => 400,
+          :code   => :api_bad_request,
+          :desc   => 'The API request is malformed.'
+        },
+        { :status => 500,
+          :code   => :security_authentication,
+          :desc   => 'An error occurred while trying to authenticate.'
+        },
+        { :status => 401,
+          :code   => :security_unauthorized,
+          :desc   => 'Valid credentials are required.'
+        },
+        { :status => 400,
+          :code   => :search_param_invalid,
+          :desc   => 'A provided search query param is invalid.'
+        },
+        { :status => 500,
+          :code   => :search_index_not_found,
+          :desc   => 'Index could not be queried for this application.'
+        },
+        { :status => 500,
+          :code   => :internal_error,
+          :desc   => 'Internal Error.'
+        },
+        { :status => 404,
+          :code   => :items_not_found,
+          :desc   => 'The requested items could not be found.'
+        },
+        { :status => 412,
+          :code   => :item_version_mismatch,
+          :desc   => 'The version of the item does not match.'
+        },
+        { :status => 412,
+          :code   => :item_already_present,
+          :desc   => 'The item is already present.'
+        },
+        { :status => 400,
+          :code   => :item_ref_malformed,
+          :desc   => 'The provided Item Ref is malformed.'
+        },
+        { :status => 409,
+          :code   => :indexing_conflict,
+          :desc   => 'The item has been stored but conflicts were detected ' +
+                     'when indexing. Conflicting fields have not been indexed.'
+        },
+    ]
+    end
+  end
+
+end

data/lib/orchestrate/api/extensions.rb

@@ -0,0 +1,14 @@
+module Orchestrate::API
+
+  # Implement the blank? helpers here, instead of requiring active_support/core_ext.
+  class ::Object
+    def blank?
+      respond_to?(:empty?) ? empty? : !self
+    end
+
+    def present?
+      !blank?
+    end
+  end
+
+end

data/lib/orchestrate/client.rb

@@ -0,0 +1,410 @@
+require 'faraday'
+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
+
+        # faraday seems to want you do specify these twice.
+        faraday.request :basic_auth, config.api_key, ''
+        faraday.basic_auth config.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 }
+    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})}
+    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.
+    #
+    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.
+    #
+    def get(collection, key, ref=nil)
+      if ref
+        send_request :get, [collection, key, 'refs', ref]
+      else
+        send_request :get, [collection, key]
+      end
+    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.
+    #
+    def put(collection, key, body, condition=nil)
+      headers={}
+      if condition.is_a?(String)
+        headers['If-Match'] = format_ref(condition)
+      elsif condition == false
+        headers['If-None-Match'] = '*'
+      end
+      send_request :put, [collection, key], { body: body, headers: headers }
+    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.
+    #
+    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.
+    #
+    def delete(collection, key, ref=nil)
+      headers = {}
+      headers['If-Match'] = 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.
+    #
+    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.
+    #
+    def get_event(collection, key, event_type, timestamp, ordinal)
+      send_request :get, [collection, key, 'events', event_type, timestamp, ordinal]
+    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.
+    #
+    def post_event(collection, key, event_type, body, timestamp=nil)
+      path = [collection, key, 'events', event_type, timestamp].compact
+      send_request :post, path, { body: body }
+    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.
+    #
+    def put_event(collection, key, event_type, timestamp, ordinal, body, ref=nil)
+      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 }
+    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.
+    #
+    def purge_event(collection, key, event_type, timestamp, ordinal, ref=nil)
+      path = [collection, key, 'events', event_type, timestamp, ordinal]
+      headers = {}
+      headers['If-Match'] = 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 }
+    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.
+    #
+    def get_relations(collection, key, *kinds)
+      path = [collection, key, 'relations'].concat(kinds)
+      send_request :get, path
+    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.
+    #
+    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.
+    #
+    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:
+    #   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
+    #
+    def in_parallel(&block)
+      accumulator = {}
+      http.in_parallel do
+        block.call(accumulator)
+      end
+      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, {})
+      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
+        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(/"/,'')}\""
+      end
+
+  end
+
+end