A new Ruby API framework

[Andrew Hodgkinson]

I work for Loyalty New Zealand (the people that run Fly Buys) and we've recently started to open source some of our core software components. One of these is a light Rack-based API framework called Hoodoo, with an associated service shell (a template analogous to that underneath "rails new ...") and API specification (analogous to the Rack specification). 

• http://loyaltynz.github.io/hoodoo
  
• https://github.com/LoyaltyNZ/hoodoo
  
• https://github.com/LoyaltyNZ/hoodoo/tree/master/docs/api_specification
• https://github.com/LoyaltyNZ/service_shell

Hoodoo has 100% rspec test coverage and 100% rdoc documentation coverage. As you'll see from the above links, there's quite a lot there; even though the software is conceptually young it's had a lot of effort spent on it, with roughly a year of development with the early six months particularly intensive.

Within Loyalty's more recent software creations, APIs are nothing new; but from Rails to Sinatra to Grape to ad hoc solutions, APIs were, despite the best efforts of architectural steering groups, disparate in their behaviour. Input semantics, response formats, error handling and security were inconsistent. Learning one API call didn't mean you could call another. Hoodoo sets out to change this, by being restrictive and opinionated in how APIs must present themselves via its API Specification, but remaining flexible in how code is laid out. It endeavours to minimise "magic" behaviour arising from special named folders or classes, complex delegation or inheritance and so-on. This is what sets it apart from otherwise more flexible popular current frameworks.

As with any software developed within a company it's a team effort, though this one is close to my heart as I've been the lead engineer on it and it has a lot of my code inside. The necessity of flattening the commit history prior to release does hide away the contributions from the team somewhat, but we've included a sanitised git log in the docs folder to give insight into its history for those who may be interested.

The AMQP-HTTP bridge for Ruby called Alchemy AMQ is due for open source release soon.

As an aside - for those also interested in Node, other architectural components based on Node.js have been released too:

• https://github.com/LoyaltyNZ/alchemy-ether
  
• http://loyaltynz.github.io/alchemy-ether
  
• https://github.com/LoyaltyNZ/alchemy-resource
  
• http://loyaltynz.github.io/alchemy-resource

We welcome any and all feedback either here or through GitHub issues. Thanks :-)

-- 
Andrew Hodgkinson
Loyalty New Zealand, Level 3, NZX Centre
11 Cable Street, Wellington 6011