Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Resource-oriented, Rack-based, minimalist web framework.
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
doc
ext
lib
test
.gitignore
README
Rakefile

README

= Watts

== Intro
Watts is a minimalist, Rack-based, resource-oriented web framework.  It
has roughly 10% as many lines of code as Sinatra, and it only does one
thing:  it maps resources.

== Goals
Dead-simple web development.  I don't want a framework to take up so
much of my brain that there's no space left for my application.

== Resource Orientation
If you think of resources as first-class objects, and then think of HTTP
methods as operations on those objects, then this should probably make
sense.

Most of the web frameworks I have seen seem to be HTTP-method-oriented
rather than resource-oriented.  It seems odd to me (not to mention
repetitive) that you would type "A GET on /foo does this, a POST on /foo
does that, ..." rather than "There's a resource at /foo.  That
resource's GET does this, and its POST does that, ...".

And because the second one made more sense to me, that's how I wrote
Watts.  Let me clarify if that was a bit vague, by showing how a Watts
app comes into being:
* You make a resource by sub-classing Watts::Resource.  
* On this resource, you define some basic operations, in terms of HTTP
methods.
* You create an app by sub-classing Watts::App.
* You use the resource() method to tell Watts the path under which the
resource can be found.

You get bonus cookies if it sounded to you like "resources" map pretty
closely to "skinny controllers".

There are a few easy-to-read examples in doc/examples.

== Pattern-matching
That resource() method mentioned above?  It does some pattern-matching
on the different components of the path.  They all arrive as strings, of
course.  The priority for matches is that Watts will attempt to match a
string literally if possible.  Next it tries to match any regex patterns
that have been specified, and failing that, symbols are used as a
catch-all.  Here are a few patterns and the things they match:
* '' matches '/'
* 'foo' matches '/foo'.
* 'foo/bar' matches '/foo/bar'.
* [] matches '/'.
* ['foo'] matches '/foo'.
* ['foo', 'bar'] matches '/foo/bar'.
* ['foo', /^[0-9+]$/] matches '/foo/', followed by a string of digits.
The matching part of the path will be passed as an argument to the
method on the resource when it is called.
* ['foo', :arg] matches '/foo/' followed by anything.  Like with the
regex, the argument is passed in.  The symbol's actual value doesn't
really matter to Watts; it is intended for documentation.

== REST, RFC 2616, TL;DR
There's a lot of talk on the internets about what exactly REST is, why
it's important, why we're doing it wrong, content-negotiation,
discoverability, avoiding out-of-band communication, and all of that
stuff.  Good gravy!  Great chowder, man!  Boring!  Watts makes it a
little easier to comply with the spec than Rails or Sinatra if you know
what the spec says, but it doesn't get all in your face about that stuff
if you don't care.  (You should definitely care, but Watts won't make you.)

== Bugs
I'm sure they're present.  You can email me about them, or ping me on
GitHub, or send a patch.

== About the Name
I named it after a character in a video game that I liked as a kid.
It's also the name of a city not far from where I live.

Also:  joules per second.

== Author
I wrote it.

== Okay, Seriously.
Pete Elmore.  Feel free to email me using pete at debu dot gs.  I'm on
GitHub at http://github.com/pete .  Also there's http://debu.gs/ , which
runs Watts.

=== Acknowledgements

The commits coming just from me is a bit misleading!  Suggestions and minor
tweaks have been provided by:

* John Dewey ( http://bitbucket.org/retr0h )
* Jim Radford ( http://github.com/radford )
* Johnathon Britz ( http://github.com/johnathonbritz )
* Justin George ( http://github.com/jaggederest )

And, as with Hoshi ( http://github.com/pete/hoshi ), I think I'll continue the
tradition of crediting the music I was blasting while writing out the first
draft:  Softball and Dance☆Man.
Something went wrong with that request. Please try again.