Orchestrate API for Ruby

Ruby client interface for the Orchestrate.io REST API.

rDoc Documentation

The Orchestrate Gem provides two interfaces currently, the method client and the object client. The method client is a solid but basic interface that provides a single entry point to an Orchestrate Application. The object client uses the method client under the hood, and maps Orchestrate's domain objects (Collections, KeyValues, etc) to Ruby classes, and is still very much in progress. This guide will show you how to use both.

app = Orchestrate::Application.new(api_key)
users = app[:users]

users[:joe] = { "name" => "Joe" }           # PUTs joe, returns the input, as per Ruby convention on #[]=
users.set(:jack, { "name" => "Jack" })      # PUTs jack, returns a KeyValue
users.create(:jill, { "name" => "Jill" })   # PUT-If-Absent hill, returns a KeyValue
users << { "name" => "Unknown" }            # POSTs the body, returns a KeyValue
users.map {|user| [user.key, user.ref]}     # enumerates over ALL items in collection

jill = users[:jill]
jill[:name]                                 # "Jill"
jill[:location] = "On the Hill"
jill.value                                  # { "name" => "Jill", "location" => "On the Hill" }
jill.save                                   # PUT-If-Match, updates ref

# method client
client = Orchestrate::Client.new(api_key)

# method client
client.put(:users, :jane, {"name"=>"Jane"}) # PUTs jane, returns API::ItemResponse
jack = client.get(:users, :jack)            # GETs jack, returns API::ItemResponse
client.delete(:users, :jack, jack.ref)      # DELETE-If-Match, returns API::Response
client.list(:users)                         # LIST users, returns API::CollectionResposne

This gem uses Faraday for its HTTP needs -- and Faraday allows you to change the underlying HTTP client used. The Orchestrate client defaults to net-http-persistent for speed on repeat requests without having to resort to a compiled library. You can easily swap in Typhoeus which uses libcurl to enable fast, parallel requests, or EventMachine HTTP to use a non-blocking, callback-based interface. 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.

If you're using a Faraday back end 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 back end 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.

client = Orchestrate::Client.new(api_key) {|f| f.adapter :typhoeus }

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] = #<Orchestrate::API::ItemResponse:0x00...>

app = Orchestrate::Application.new(api_key) {|f| f.adapter :typhoeus }

app.in_parallel do
  @items = app[:my_collection].lazy.take(100)
  @user = app[:users][current_user_id]
end

Note that values are not available inside of the in_parallel block. The r[:list] or @items objects are placeholders for their future values and will be available after the in_parallel block returns. Since take and other enumerable methods normally attempt to access the value when called, you must convert the app[:my_collection] enumerator to a lazy enumerator with #lazy. Attempting to access the enumerator's values (for example, without using #lazy or by using #any? or #find) while inside the in_parallel block will raise an Orchestrate::ResultsNotReady exception.

Lazy Enumerators are not available by default in Ruby 1.9.

Typhoeus is backed by libcurl and enables parallelization.

require 'orchestrate'
require 'typhoeus/adapters/faraday'

client = Orchestrate::Client.new(api_key) do |conn|
  conn.adapter :typhoeus
end

EM-HTTP-Request is an HTTP client for Event Machine. It enables callback support and parallelization.

require 'em-http-request'

client = Orchestrate::Client.new(api_key) do |conn|
  conn.adapter :em_http
end

EM-Synchrony is a collection of utility classes for EventMachine to help untangle evented code. It enables parallelization.

require 'em-synchrony'

client = Orchestrate::Client.new(api_key) do |conn|
  conn.adapter = f.adapter :em_synchrony
end

• Fix #66 to make parallel mode work properly
• Switch the default Faraday adapter to the net-http-persistent gem, which in casual testing yields much better performance for sustained use.
• Introduced the object client, Orchestrate::Application, Orchestrate::Collection & Orchestrate::KeyValue

• Fix #55 to handle ping responses when unauthorized

• Fix #48 to remove trailing -gzip from Etag header for ref value.
• Custom #to_s and #inspect methods for Client, Response classes.
• Implement If-Match header for Client#purge
• Implement Client#post for auto-generated keys endpoint

• Fix #43 for If-None-Match on Client#put
• Fix #46 for Client#ping
• License changed to ASLv2

• BACKWARDS-INCOMPATIBLE Reworked Client constructor to take API key and optional Faraday configuration block. See 9045ffc for details.
• Migrated documentation to YARD
• Provide basic response wrappers specific to generic request types.
• Raise Exceptions on error response from Orchestrate API.
• Remove custom logger in favor of the option to use Faraday middleware.
• Accept Time/Date objects for Timestamp arguments to Event-related methods.

• Fix problem with legacy code preventing gem from loading in some environments

Initial Port from @jimcar

• Uses Faraday HTTP Library as backend, with examples of alternate adapters
• Cleanup client method signatures