Hoodoo Guides: Home

What is Hoodoo?

The Hoodoo Gem

Hoodoo is a Ruby Gem developed by Loyalty New Zealand that works with Rack to provide a framework for creating highly consistent RESTful, CRUD APIs with minimal code. It differs from frameworks such as Rails or Sinatra by being entirely focused on APIs and differs from frameworks such as Grape by enforcing strict conventions to minimise API inconsistencies.

Hoodoo’s code has 100% coverage via RDoc and 100% non-trivial automated test coverage via RSpec according to RCov. Out-of-the-box logging support includes I/O stream, file and LogEntries writers, and exception reporters include Raygun and Airbrake. It’s easy to write new log and exception sinks if you need them.

Hoodoo services can run under any Rack-compliant web server but for truly decoupled, scalable and highly available deployments, use Alchemy.

The Hoodoo API Specification

The Hoodoo API Specification describes the conventions that Hoodoo enforces. In many respects, this specification is to Hoodoo as the Rack Interface Specification is to Rack. API endpoint authors require a reasonable understanding of the Specification so they know what is expected of their services.

Minimal example

This is a very brief example showing you how to install some required gems and get a Resource endpoint up and running all in a single Ruby file. The code is pulled apart and explained in detail in the Fundamentals Guide, which also includes other more useful examples.

Install gems

Install Thin, Rack and Hoodoo:

gem install thin
gem install rack
gem install hoodoo

The service code

require 'rack'
require 'hoodoo'

class TimeImplementation < Hoodoo::Services::Implementation
  def show( context )
    context.response.set_resource( { 'time' => Time.now.utc.iso8601 } )
  end
end

class TimeInterface < Hoodoo::Services::Interface
  interface :Time do
    endpoint :time, TimeImplementation
    public_actions :show
  end
end

class TimeService < Hoodoo::Services::Service
  comprised_of TimeInterface
end

# This is a hack for the example and needed if you have Active Record present,
# else Hoodoo will expect a database connection.
#
Object.send( :remove_const, :ActiveRecord ) rescue nil

builder = Rack::Builder.new do
  use( Hoodoo::Services::Middleware )
  run( TimeService.new )
end

Rack::Handler::Thin.run( builder, :Port => 9292 )

Start the service

ruby <filename.rb>

Make an API call

Now you can talk to it with, say, cURL. Note that Hoodoo requires the Content-Type header as shown:

curl http://127.0.0.1:9292/v1/time/now --header 'Content-Type: application/json; charset=utf-8'
# => {"time":"2015-08-03T02:31:34Z"}

Other frequently used test clients are the Postman extension for Google Chrome, Paw on Mac OS X, or use Ruby and Hoodoo::Client, described in the Hoodoo::Client Guide.