/ 
Sloth-0.05
River stage zero No dependents
/ Sloth

NAME

Sloth - A PSGI compatible REST framework

SYNOPSIS

# app.psgi
use strict;
use warnings;

# See Sloth::Manual for more information on building MyApp
use MyApp;
MyApp->new;

DESCRIPTION

Sloth is a framework for building a RESTful Web service. Sloth allows you to define resources, methods to operate on these resources, and representations of these resources and their results, while doing the plumbing to bind it all together for you.

Sloth is also a PSGI basedframework. This means that it is a framework that can be deployed on PSGI compatible server software, such as Starman, Twiggy, but also standard server such as Apache and anything that can understand FastCGI.

WHY?

Sloth was born out of the MusicBrainz project while refactoring our existing Catalyst REST controllers. They were considerably tied to a single representation (XML), and had a large amount of plumbing. The state of the art in terms of Catalyst has got better (see Catalyst::Action::REST for example), however I still think we can do better.

I also wanted felt that I didn't need the entire Catalyst stack, and that by rolling something domain-specific I could by at lot more concise in specifying the necessary logic. By using PSGI, we benefit immediately from potential high performance, by hosting on servers that speak directly to PSGI, too - and as our web service accounted for 90% of traffic, performance was certainly a motivating factor!

ATTRIBUTES

representations

A ArrayRef[Sloth::Representation] of all known representations of resources.

resources

A ArrayRef[Sloth::Resource] of all servable resources.

router

A Path::Router defining the possible URIs in this API. Each path in the router is expected to have a target that points to a Sloth::Resource.

METHODS

resource_arguments

$self->resource_arguments : @List

Generate a set of parameters that will be passed to resources. If your resources all require a set of common, shared objects, you can override this to provide those extra initialization arguments.

mock

$self->mock(GET '/foo')

Allows you to give a HTTP::Request object to your application, and have be requested, and possibly treated slightly different than other requests.

If an Accept header is not present in the request, Sloth will automatically set it to Accept: mock/ref. You can then provide a representation that returns a Perl reference, rather than actually performing any serialization. This can make testing your resources and methods significantly easier.

call

$self->call($psgi_env : HashRef)

Entry point for each request. This is called for you via the PSGI specification from your server.

IMPORTANT DOCUMENTATION

The following pieces of documentation are what I consider to be key to understanding how to use Sloth:

Sloth::Manual::Architecture

Explains how the various parts of Sloth interact with each other, how they are glued together by default, and how you can replace this with your own glue.

AUTHOR

Oliver Charles

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Oliver Charles <sloth.cpan@ocharles.org.uk>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.