restfulness 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ddaa3efca8063cce4459e78242665f30c7aa7beb
+  data.tar.gz: 39fc6f40248c0a0453ce566fc97537920977e529
+SHA512:
+  metadata.gz: 205f618a6e3d7968e9e365e5a90abbbe335ebc994179da9030bc6d57d2bcafacfa9b001f612beea36490e18a2ed8344a2e19e772d70071b266500ba31832b7ec
+  data.tar.gz: f2c6c07d14351f6f05e270f34df4b23b08dea402a82b0988cc8ed4076d960d379b88c1bc2384ebcfcb9b7b80c372d681a790558d40b241b09bd5c3fea4ca9a11

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in restfulness.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Sam Lown
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,342 @@
+# Restfulness
+
+Because REST APIs are all about resources, not routes.
+
+## Introduction
+
+Restfulness is an attempt to create a Ruby library that helps create truly REST based APIs to your services. The focus is placed on performing HTTP actions on resources via specific routes, as opposed to the current convention of assigning routes and HTTP actions to methods or blocks of code. The difference is subtle, but makes for a much more natural approach to building APIs.
+
+The current version is very minimal, as it only support JSON content types, and does not have more advanced commonly used HTTP features like sessions or cookies. For most APIs this should be sufficient.
+
+To try and highlight the diferences between Restfulness and other libraries, lets have a look at a couple of examples.
+
+[Grape](https://github.com/intridea/grape) is a popular library for creating APIs in a "REST-like" manor. Here is a simplified section of code from their site:
+
+```ruby
+module Twitter
+  class API < Grape::API
+
+    version 'v1', using: :header, vendor: 'twitter'
+    format :json
+
+    resource :statuses do
+
+      desc "Return a public timeline."
+      get :public_timeline do
+        Status.limit(20)
+      end
+
+      desc "Return a personal timeline."
+     get :home_timeline do
+        authenticate!
+        current_user.statuses.limit(20)
+      end
+
+      desc "Return a status."
+      params do
+        requires :id, type: Integer, desc: "Status id."
+      end
+      route_param :id do
+        get do
+          Status.find(params[:id])
+        end
+      end
+
+    end
+
+  end
+end
+
+```
+
+The focus in Grape is to construct an API by building up a route hierarchy where each HTTP action is tied to a specific ruby block. Resources are mentioned, but they're used more for structure or route-seperation, than a meaningful object.
+
+Restfulness takes a different approach. The following example attempts to show how you might provide a similar API:
+
+```ruby
+class TwitterAPI < Restfullness::Application
+  routes do
+    add 'status',             StatusResource
+    add 'timeline', 'public', PublicTimelineResource
+    add 'timeline', 'home',   HomeTimelineResource
+  end
+end
+
+class StatusResource < Restfulness::Resource
+  def get
+    Status.find(request.path[:id])
+  end
+end
+
+class PublicTimelineResource < Restfulness::Resource
+  def get
+    Status.limit(20)
+  end
+end
+
+# Authentication requires more cowbell, so assume the ApplicationResource is already defined
+class HomeTimelineResource < ApplicationResource
+  def authorized?
+    authenticate!
+  end
+  def get
+    current_user.statuses.limit(20)
+  end
+end
+
+```
+
+I, for one, welcome our new resource overloads. They're a clear and consise way of separating logic between different classes, so an individual model has nothing to do with a collection of models, even if the same model may be provided in the result set.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'restfulness'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install restfulness
+
+## Usage
+
+### Defining an Application
+
+A Restfulness application is a Rack application whose main function is to define the routes that will forward requests on a specific path to a resource. Your applications inherit from the `Restfulness::Application` class. Here's a simple example:
+
+```ruby
+class MyAppAPI < Restfulness::Application
+  routes do
+    add 'project',  ProjectResource
+    add 'projects', ProjectsResource
+  end
+end
+
+```
+
+An application is designed to be included in your Rails, Sinatra, or other Rack project, simply include a new instance of your application in the `config.ru` file:
+
+```ruby
+run Rack::URLMap.new(
+  "/"       => MyRailsApp::Application,
+  "/api"    => MyAppAPI.new
+)
+```
+
+By default, Restfulness comes with a Rack compatible dispatcher, but in the future it might make sense to add others.
+
+If you want to run Restfulness standalone, simply create a `config.ru` that will load up your application:
+
+```ruby
+require 'my_app'
+run MyApp.new
+```
+
+You can then run this with rackup:
+
+```
+bundle exec rackup
+```
+
+For an example, checkout the `/example` directory in the source code.
+
+
+### Routes
+
+The aim of routes in Restfulness are to be stupid simple. These are the basic rules:
+
+ * Each route is an array that forms a path when joined with `/`.
+ * Order is important.
+ * Strings are matched directly.
+ * Symbols match anything, and are accessible as path attributes.
+ * Every route automically gets an :id parameter at the end, that may or may not have a null value.
+
+Lets see a few examples:
+
+```ruby
+routes do
+  # Simple route to access a project, access with:
+  #   * PUT /project
+  #   * GET /project/1234
+  add 'project',  ProjectResource
+
+  # Parameters are also supported.
+  # Access the project id using `request.path[:project_id]`
+  add 'project', :project_id, 'status', ProjectStatusResource
+end
+```
+
+
+### Resources
+
+Resources are like Controllers in a Rails project. They handle the basic HTTP actions using methods that match the same name as the action. The result of an action is serialized into a JSON object automatically. The actions supported by a resource are:
+
+ * `get`
+ * `head`
+ * `post`
+ * `put`
+ * `delete`
+ * `options` - this is the only action provded by default
+
+When creating your resource, simply define the methods you'd like to use and ensure each has a result:
+
+```ruby
+class ProjectResource < Restfulness::Resource
+  # Return the basic object
+  def get
+    project
+  end
+
+  # Update the object
+  def put
+    project.update(params)
+  end
+
+  protected
+
+  def project
+    @project ||= Project.find(request.path[:id])
+  end
+end
+```
+
+Checking which methods are available is also possible by sending an `OPTIONS` action. Using the above resource as a base:
+
+    curl -v -X OPTIONS http://localhost:9292/project
+
+Will include an `Allow` header that lists: "GET, PUT, OPTIONS".
+
+Resources also have support for simple set of built-in callbacks. These have similar objectives to the callbacks used in [Ruby Webmachine](https://github.com/seancribbs/webmachine-ruby) that control the flow of the application using HTTP events.
+
+The supported callbacks are:
+
+ * `exists?` - True by default, not called in create actions like POST.
+ * `authorized?` - True by default, is the current user valid?
+ * `allowed?` - True by default, does the current have access to the resource?
+ * `last_modified` - The date of last update on the model, only called for GET and HEAD requests. Validated against the `If-Modified-Since` header.
+ * `etag` - Unique identifier for the object, only called for GET and HEAD requests. Validated against the `If-None-Match` header.
+
+To use them, simply override the method:
+
+```ruby
+class ProjectResource < Restfulness::Resource
+  # Does the project exist? only called in GET request
+  def exists?
+    !project.nil?
+  end
+
+  # Return a 304 status if the client can used a cached resource
+  def last_modified
+    project.updated_at.to_s
+  end
+
+  # Return the basic object
+  def get
+    project
+  end
+
+  # Update the object
+  def post
+    Project.create(params)
+  end
+
+  protected
+
+  def project
+    @project ||= Project.find(request.path[:id])
+  end
+end
+```
+
+
+### Requests
+
+All resource instances have access to a `Request` object via the `#request` method, much like you'd find in a Rails project. It provides access to the details including in the HTTP request: headers, the request URL, path entries, the query, body and/or parameters.
+
+Restfulness takes a slightly different approach to handling paths, queries, and parameters. Rails and Sinatra apps will typically mash everything together into a `params` hash. While this is convenient for most use cases, it makes it much more difficult to separate values from different contexts. The effects of this are most noticable if you've ever used Models Backbone.js or similar Javascript library. By default a Backbone Model will provide attributes without a prefix in the POST body, so to be able to differenciate between query, path and body parameters you need to ignore the extra attributes, or hack a part of your code to re-add a prefix.
+
+The following key methods are provided in a request object:
+
+```ruby
+# A URI object
+request.uri                # #<URI::HTTPS:0x00123456789 URL:https://example.com/somepath?x=y>
+
+# Basic request path
+request.path.to_s          # '/project/123456'
+request.path               # ['project', '123456']
+request.path[:id]          # '123456'
+request.path[0]            # 'project
+
+# More complex request path, from route: ['project', :project_id, 'task']
+request.path.to_s          # '/project/123456/task/234567'
+request.path               # ['project', '123456', 'task', '234567']
+request.path[:id]          # '234567'
+require.path[:project_id]  # '123456'
+require.path[2]            # 'task'
+
+# The request query
+request.query              # {:page => 1} - Hash with indifferent access
+request.query[:page]       # 1
+
+# Request body
+request.body               # "{'key':'value'}" - string payload
+
+# Request params
+request.params             # {'key' => 'value'} - usually a JSON deserialized object
+```
+
+## Caveats and TODOs
+
+Restfulness is still very much a work in progress. Here is a list of things that we'd like to improve or fix:
+
+ * Support for more serializers, not just JSON.
+ * Reloading is a PITA (see note below).
+ * Needs more functional testing.
+ * Support for before and after filters in resources, although I'm slightly aprehensive about this.
+
+## Reloading
+
+Reloading is complicated. Unfortunately we're all used to the way Rails projects magically reload changed files so you don't have to restart the server after each change.
+
+If you're using Restfulness as a standalone project, we recommend using a rack extension like [Shotgun](https://github.com/rtomayko/shotgun).
+
+If you're adding Restfulness to a Rails project, you can take advantage of the `ActionDispatch::Reloader` rack middleware. Simply include it in the application definition:
+
+```ruby
+class MyAPI < Restfulness::Application
+  if Rails.env.development?
+    middlewares << ActionDispatch::Relaoder
+  end
+  routes do
+    # etc. etc.
+  end
+```
+
+We're still working on ways to improve this. If you have any ideas, please send me a pull request!
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write your code and test the socks off it!
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+
+## Contributors
+
+Restfulness was created by Sam Lown <me@samlown.com> as a solution for building simple APIs at [Cabify](http://www.cabify.com).
+
+
+## History
+
+### 0.1.0 - October 16, 2013
+
+First release!
+
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/example/Gemfile

@@ -0,0 +1,5 @@
+
+source 'https://rubygems.org'
+
+gem 'restfulness', path: '../'
+

data/example/README.md

@@ -0,0 +1,42 @@
+
+# Restfulness Example App
+
+Really simple example of a basic app with a couple of resources.
+
+## Preparation
+
+Use bundler to make sure all the dependencies are in place:
+
+    cd example
+    bundle install
+
+By default, bundler will expect to find the restfulness gem provided in the parent directory.
+
+## Running
+
+    bundle exec runit
+
+## Testing
+
+Curl is your friend!
+
+    # Get nothing (returns 404)
+    curl -v http://localhost:9292/projects
+
+    # Post a journey
+    curl -v -X POST http://localhost:9292/project -H "Content-Type: application/json" -d "{\"id\":\"project1\",\"name\":\"First Project\"}"
+
+    # Retrieve it
+    curl -v http://localhost:9292/project/project1
+
+    # Get an array of projects
+    curl -v http://localhost:9292/projects
+    
+    # Try updating it
+    curl -v -X PUT http://localhost:9292/project/project1 -H "Content-Type: application/json" -d "{\"name\":\"First Updated Project\"}"
+
+    # Finally remove it and check the list is empty
+    curl -v -X DELETE http://localhost:9292/project/project1
+    curl -v http://localhost:9292/projects
+
+