Halcyon

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

Responding to the Client

This is a comprehensive overview of the various ways in which to respond to
requests from clients, going from the simplest, standard response (using the
ok and not_found methods) to issuing standard errors
and even responding with the standard Rack format.

Rack Response

Since Halcyon is a Rack-based application, responding to requests follows the
simple format:

1 [status, headers, body]

For example, a simple response could be:

1 [200, {}, 'OK']

In fact, the above is close to what results by calling ok.

Standard Responses

The ok method will be the primary response method call, simply
wrapping the body of the message into a standard Rack response with the status
set to 200 and headers set appropriately (though additional headers
are set before responses are sent) with the body being set with a specific
format:

{:status => status, :body => body}

The status code does appear twice: this is on purpose, providing the clients
with status information that they would otherwise have to repackage from the
HTTP response as well. Also, since JSON requires a minimum of a hash or array,
this meets this minimum requirement while allowing you to respond with simple
primitives such as plain integers or strings without having to wrap it manually.

A simple example of using ok:

1 ok "OK" #=> [200, {}, {:status => 200, :body => 'OK'}]

and in context:

1 class Messages < Application
2   def show
3     ok Message[params[:id]].to_json
4   end
5 end

This will take the instance of Message (a
Sequel model object in this example) and
call to_json on it before passing it to ok which wraps
it in the standard Halcyon response format:

1 [
2   200,
3   {},
4   {:status => 200, :body => {
5     :id => 40, :message => 'foo'}
6   }.to_json
7 ]

The above example shows you what the body of the response would be before
Halcyon converts it to JSON (hence to_json appearing at the end).

The following methods are available: ok (status code:
200) and not_found (status code: 404).
More are planned for later.

Errors

Halcyon provides several exception classes that can be raised to simplify error
handling. These exceptions all model the standard HTTP errors, mapping to the
200, 300, 400, and 500 errors (and, in fact, they are not all errors, but can
still be raised to simplify responding with this status code and message).

For example:

 1 class Messages < Application
 2   def create
 3     msg = Message.create(params)
 4     if msg.save
 5       raise Created.new
 6     else
 7       ok UnprocessableEntity.new
 8     end
 9   end
10 end

It is not necessarily required or even recommended to raise an exception like
this to respond, but it is certainly possible and for a pure
RESTful application it can remove the tedium
of having to manually specify the status code and message.

The most common example would be closer to the following:

1 class Messages < Application
2   def show
3     ok Message[params[:id]] or raise NotFound.new
4   end
5 end

The best place to see all of the status codes available would be to view the
source code (view source)
or at http://www.askapache.com/htaccess/apache-status-code-headers-errordocument.html.

Custom Responses

As indicated above, the standard response format follows something like this:

1 [status, headers, body]

This is the format indicated in the Rack specification for response. If you
would like to create a custom response, forgoing the standard ok
et al methods or the exception classes, or you do not need the body wrapped up
in a hash ( like {:status => status, :body => body}), you can
specify your own response manually. For instance:

1 class Messages < Application
2   def list
3     [200, {}, Message.all]
4   end
5 end

Extra flexibility with responses, such as just responding with the body and the
status being assumed 200, is planned for the future.