Notice: The website is currently being udpated. Sorry for any inconvenience.

Introduction to Halcyon

Halcyon is a simple framework to ease development of service-oriented
applications, such as public or private APIs or custom services for


This is the what is Halcyon for? question and basically summarizes why anyone
would need to use Halcyon. Halcyon’s purpose is to provide a dedicated,
simplistic application development framework for exposing functionality through
HTTP/JSON requests, removing the need for content-negotiation or explicitly
formatting everything to the JSON format.

On top of this technical level, the goal of Halcyon is to make building
service-oriented applications quick and easy, removing the general cruft of
rendering JSON, etc. Halcyon tries to handle all of the mechanics
associated with getting an SOA running.

An Example

This can be hard to grasp at immediately, so let’s take a look at an example:
Twitter provides a service centered around tiny
(140-character limit) messages being aggregated for friends and family. Twitter
also provides a service for making third party clients to send messages to or
read messages from Twitter without having to be on the website.

Twitter does this by exposing URLs for applications to send data to and pull
data from. The Twitter API (what they’ve called this interface to their
application functionality) can be seen at
The Twitter API page
with several examples of how to use Twitter outside of the website.

For example, to post a new message (or a status update as Twitter calls it),
you would POST the data to http://twitter.com/statuses/update.xml.

Twitter responds in XML and expects XML as its input in some cases, whereas
Halcyon applications (for now) just use JSON. JSON is widely accepted and used
across the web and competes with XML.

Halcyon could just as easily provide an API to a given application, routing
requests to controllers with specific actions without the need to negotiate the
content types requested (application/json) or define views.

The Framework

As a framework, Halcyon breaks your application code up into controllers with
absolutely no views and no predefined system for models or database
connectivity. Routes are used to define what paths are handled by what actions
in which controllers.

Halcyon distinguishes itself by the distinct combination of technologies it
employs to simplify its task. To clarify, Halcyon specifically chooses to
reinvent as little as possible and yet provide a great deal of functionality.
We do this by using standard HTTP protocols, transferring complex data across
platforms with JSON, designing Halcyon apps on top of
Rack, and even reusing portions of
Merb to prevent duplication. Here’s a quick look at
each of these.


JSON, or JavaScript Object Notation, is a simple format to transport complex
data structures across the HTTP medium and across to many platforms. It’s a
simple format like XML, easy to read and write (unlike XML), and serializable.
CouchDB chose JSON over XML for similar reasons, and has
been very happy with the decision.


Hypertext Transfer Protocol is a widely support protocol, supported on pretty
much every platform, and provides a familiar way to modify resources with
Representational State Transfer.


Rack provides a uniform model for handling HTTP request and response cycles,
allowing for server-independent development and for powerful layering of
applications and specialized functionality through middleware.

Jim Weirich’s talk at MountainWest 2008 focuses on the power of simplicity.
Specifically, Jim mentions three poignant parts to a powerful system, having:

  1. Small Core
  2. Simple Rules
  3. Powerful Abstractions

Rack’s design elegantly shows off the power of its simplicity.


Having Merb as a dependency of Halcyon seems a bit ironic, but its active
community, quality modular code, and thorough documentation provides an
excellent souce of functionality without all of the repetitive development.
Halcyon specifically takes advantage of the Merb Router and the Core Extensions.


Halcyon started off as a centralized authentication system for numerous
applications on varied platforms, at the time called Aurora. The decision was
made to split Aurora into a framework and an application, Halcyon becoming the


Any web application framework should be a sufficient alternative, and may
provide a better solution. Here are several frameworks that could be used
instead of Halcyon, though may require more effort to handle the incoming and
outgoing JSON requests.

A more comprehensive list can be found at
the Ramaze website.