restfulness 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8b7f899ce27987a0fc7cd6bfd1d272e999921b4a
-  data.tar.gz: 4c37afe53ef267decffc2d72b7fab1b5407bc2ae
+  metadata.gz: ce9b42d05b92e2107f89ce16f36a5f1bbfabe6e7
+  data.tar.gz: b9cb7bdc241661ab063b45f20a81a967f43eeee6
 SHA512:
-  metadata.gz: 099b1309377a645b8fad3c13116aa5e65d87a43dc0caa4987a05e1b7aefce60a6265e6f0911c7728675e99d5bed40ec2b7c9aab5d717618261f45b23413c23b9
-  data.tar.gz: 0fa3111acd852dfec3d0b3fe14ab02eae9b3288dcd7e32e81da062072f4e6ac3888aebe6b63c958652ea2beac1954d322f16ae60b6ac4d5a185e28cbe0cf7256
+  metadata.gz: 7809aad851643407a59b3d376a75d39c4a1f703cf18cc647817e018971434e547dd8fbfcbd6b01e6dafb3aa7e510eee7233ca5a75ecf839239b52596e5bac5ca
+  data.tar.gz: f8fbe0c48f0a05bd5f50f48ccb56545afed3408ed5d4941ffd7db5303dbb107203b6656de0c7f13cf937bb88ee716dd2b7d8a7499681abdfbdc2492dc3f14206

data/.gitignore

@@ -17,3 +17,4 @@ test/tmp
 test/version_tmp
 tmp
 *.swp
+*.swo

data/.travis.yml

@@ -1,9 +1,10 @@
 language: ruby
 rvm:
+  - 2.3.0
+  - 2.2.2
+  - 2.1.5
   - 2.0.0
-  - 1.9.3
   - jruby-19mode # JRuby in 1.9 mode
-  - rbx # Probably a bit optimistic
-matrix:
-  allow_failures:
-    - rvm: rbx
+  - rbx
+before_install:
+  - gem install bundler

data/README.md

@@ -6,93 +6,97 @@ 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.
+Restfulness is a simple Ruby library for creating REST APIs. Each endpoint defined in the routing configuration refers to a resource class containing HTTP actions and callbacks. When an HTTP request is received, the callbacks are checked, and the appropriate action is called to provide a response.
 
-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.
+When creating Restfulness, we had a set of objectives we wanted to achieve:
 
-To try and highlight the diferences between Restfulness and other libraries, lets have a look at a couple of examples.
+ * A true "resource" orientated interface.
+ * Simple routing.
+ * Fast.
+ * JSON only responses.
+ * Take advantage of HTTP flow control using callbacks.
+ * Simple error handling, and "instant abort" exceptions.
 
-[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:
+Here's a code example of what the restfulness side of a rack application might look like:
 
 ```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
+# The API definition, this matches incoming request paths to resources
+class TwitterAPI < Restfullness::Application
+  routes do
+    scope 'api' do
+      add 'task',      Tasks::ItemResource
+      scope 'tasks' do
+        add 'public',  Tasks::PublicResource
+        add 'private', Tasks::PrivateResource
       end
-
     end
-
   end
 end
 
-```
+# Modules are always a good idea to group resources
+module Tasks
+  # A simple resource for returning tasks
+  class ItemResource < Restfulness::Resource
+    # Callback to see if task exsists
+    def exists?
+      !!task
+    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.
+    # Provide the task, if the #exists? call worked
+    def get
+      task  
+    end
 
-Restfulness takes a different approach. The following example attempts to show how you might provide a similar API:
+    # Create a new task, this will bypass the #exits? call
+    def post
+      Task.create(request.params)
+    end
 
-```ruby
-class TwitterAPI < Restfullness::Application
-  routes do
-    add 'status',             StatusResource
-    scope 'timeline' do
-      add 'public', Timelines::PublicResource
-      add 'home',   Timelines::HomeResource
+    # Update the task, and raise an error with error response if failed
+    def patch
+      task.update_attributes(request.params) || forbidden!(task.errors)
     end
-  end
-end
 
-class StatusResource < Restfulness::Resource
-  def get
-    Status.find(request.path[:id])
+    protected
+
+    def task
+      @task ||= Task.find(request.path[:id])
+    end
   end
-end
 
-module Timelines
+  # Simple resource that provides list of public tasks, that may be empty
   class PublicResource < Restfulness::Resource
     def get
-      Status.limit(20)
+      Task.public.limit(20)
     end
   end
 
-  # Authentication requires more cowbell, so assume the ApplicationResource is already defined
-  class HomeResource < ApplicationResource
+  # Authorization requires additional code to authenticate the user
+  class PrivateResource < Restfulness::Resource
+    # If this fails, abort and return 401 Unauthorized response
     def authorized?
-      authenticate!
+      !current_user
     end
+
+    # Assuming authorized, attept to load tasks
     def get
-      current_user.statuses.limit(20)
+      current_user.tasks.limit(20)
+    end
+
+    protected
+
+    # Very simple example of authentication
+    def current_user
+      @current_user ||= authenticate_with_http_basic do |username, password|
+        User.authenticate(username, password)
+      end
     end
   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.
+Checkout the rest of this document for more of the details on the api, integration with your existing apps, and additional features.
 
 
 ## Installation
@@ -159,7 +163,7 @@ The aim of routes in Restfulness are to be stupid simple. These are the basic ru
  * 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.
+ * Every route automatically gets an :id parameter at the end, that may or may not have a null value.
  * Scopes save repeating shared route array entries.
 
 Lets see a few examples:
@@ -204,7 +208,7 @@ 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:
+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`
@@ -212,7 +216,7 @@ Resources are like Controllers in a Rails project. They handle the basic HTTP ac
  * `patch`
  * `put`
  * `delete`
- * `options` - this is the only action provded by default
+ * `options` - this is the only action provided by default
 
 When creating your resource, simply define the methods you'd like to use and ensure each has a result:
 
@@ -286,11 +290,11 @@ end
 
 #### I18n in Resources
 
-Restfulness uses the [http_accept_language](https://github.com/iain/http_accept_language) gem to automatically handle the `Accept-Language` header coming in from a client. After trying to make a match between the available locales, it will automatically set the `I18n.locale`. You can access the http_accept_language parser via the `request.http_accept_language` method.
+Restfulness uses the [http_accept_language](https://github.com/iain/http_accept_language) gem to automatically handle the `Accept-Language` header received from a client. After trying to make a match between the available locales, it will automatically set the `I18n.locale`. You can access the http_accept_language parser via the `request.http_accept_language` method.
 
 For most APIs this should work great, especially for mobile applications where this header is automatically set by the phone. There may however be situations where you need a bit more control. If a user has a preferred language setting for example.
 
-Resources contain two protected methods that can be overwritten if you need more precise control. This is what they look like in the Restfulness code:
+Resources contain two protected methods that can be overwritten. This is what they look like in the Restfulness code:
 
 ```ruby
 protected
@@ -302,16 +306,15 @@ end
 def set_locale
   I18n.locale = locale
 end
-``` 
+```
 
 The `Resource#set_locale` method is called before any of the other callbacks are handled. This is important as it allows the locale to be set before returning any translatable error messages.
 
-Most users will probably just want to override the `Resource#locale` method and provide the appropriate locale for the request. If you are using a User object or similar, double check your authentication process as the default `authorized?` method will be called *after* the locale is prepared.
-
+Most users will probably just want to override the `Resource#locale` method and provide the appropriate locale for the request. If you are using a User object or similar, double check your authentication process as the default `authorized?` method will be called *after* the locale is prepared so that error responses are always in the requested language.
 
 #### Authentication in Resources
 
-Restfulness now provides very basic support for the [HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication). To use it, simply call the `authenticate_with_http_basic` method in your resource definition.
+Restfulness provides basic support for [HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication). To use, simply call the `authenticate_with_http_basic` method in your resource definition.
 
 Here's an example with the authentication details in the code, you'd obviously want to use something a bit more advanced than this in production:
 
@@ -332,9 +335,9 @@ def authorized?
 end
 ```
 
-We don't yet provide support for Digest authentication, but your contributions would be more than welcome. Checkout the [HttpAuthentication/basic.rb](https://github.com/samlown/restfulness/blob/master/lib/restfulness/http_authentication/basic.rb) source for an example.
+Digest authentication is not currently supported, but your contributions would be more than welcome. Checkout the [HttpAuthentication/basic.rb](blob/master/lib/restfulness/http_authentication/basic.rb) source for an example.
 
-Restfulness doesn't make any provisions for requesting authentication from the client as most APIs don't really need to offer this functionality. You can acheive the same effect however by providing the `WWW-Authenticate` header in the response. For example:
+Restfulness doesn't make any provisions for requesting authentication from the client as in our experience most APIs don't need to offer this functionality. You can achieve the same effect however by providing the `WWW-Authenticate` header in the response. For example:
 
 ```ruby
 def authorized?
@@ -353,12 +356,11 @@ def request_authentication
 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.
+All resource instances have access to a `Request` object via the `Resource#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.
+Restfulness takes a slightly different approach to handling paths, queries, and parameters, as each has their own independent method. Rails and Sinatra will typically mash everything together into a `params` hash. While this is convenient for use cases involving a browser, it is less useful for APIs when body parameters should only contain attributes of the model managed by the resource. If you've ever used Models from Backbone.js or similar Javascript library you appreciate this. When saving a Model, Backbone.js assumes by default that attributes will be provided without a prefix in the POST body.
 
 The following key methods are provided in a request object:
 
@@ -387,7 +389,13 @@ request.query[:page]       # 1
 request.body               # "{'key':'value'}" - string payload
 
 # Request params
-request.params             # {'key' => 'value'} - usually a JSON deserialized object
+request.params             # {'key' => 'value'} - usually a JSON de-serialized object
+
+# Accept header object (nil if none!)
+request.accept.version     # For "Accept: application/vnd.example.api+json;version=3", returns "3"
+
+# Content Type object (nil if none!)
+request.content_type.to_s  # Something like "application/json"
 ```
 
 ### Logging
@@ -408,7 +416,7 @@ Restfulness.sensitive_params = [:password, :secretkey]
 
 ## Error Handling
 
-If you want your application to return anything other than a 200 (or 202) status, you have a couple of options that allow you to send codes back to the client.
+If you'd like your application to return anything other than a 200 (or 202) status, you have a couple of options that allow you to send codes back to the client.
 
 One of the easiest approaches is to update the `response` code. Take the following example where we set a 403 response and the model's errors object in the payload:
 
@@ -470,7 +478,7 @@ end
 
 This can be a really nice way to mold your errors into a standard format. All HTTP exceptions generated inside resources will pass through `error!`, even those that a triggered by a callback. It gives a great way to provide your own JSON error payload, or even just resort to a simple string.
 
-The currently built in error methods are:
+The currently built in exception methods are:
 
  * `not_modified!`
  * `bad_request!`
@@ -499,19 +507,19 @@ We're all used to the way Rails projects magically reload files so you don't hav
 
 Using Restfulness in Rails is the easiest way to take advantage support reloading.
 
-The recomended approach is to create two directories in your Rails projects `/app` path:
+The recommended approach is to create two directories in your Rails projects `/app` path:
 
  * `/app/apis` can be used for defining your API route files, and
  * `/app/resources` for defining a tree of resource definition files.
 
-Add the two paths to your rails autoloading configuration in `/config/application.rb`, there will already be a sample in your config provided by Rails:
+Add the two paths to your rails auto-loading configuration in `/config/application.rb`, there will already be a sample in your config provided by Rails:
 
 ```ruby
 # Custom directories with classes and modules you want to be autoloadable.
 config.autoload_paths += %W( #{config.root}/app/resources #{config.root}/app/apis )
 ```
 
-Your Resource and API files will now be autoloadable from your Rails project. The next step is to update our Rails router to be able to find our API. Modify the `/config/routes.rb` file so that it looks something like the following:
+Your Resource and API files will now be auto-loadable from your Rails project. The next step is to update the Rails router to be able to find our API. Modify the `/config/routes.rb` file so that it includes the mount method call:
 
 ```ruby
 YourRailsApp::Application.routes.draw do
@@ -526,7 +534,7 @@ end
 
 ```
 
-You'll see in the code sample that we're only loading the Restfulness API during development. Our recommendation is to use Restfulness as close to Rack as possible and avoid any of the Rails overhead. To support request in production, you'll need to update your `/config.rb` so that it looks something like the following:
+You'll see in the code sample that we're only loading the Restfulness API during development. Our recommendation is to use Restfulness as close to Rack as possible and avoid any of the Rails overhead. To support requests in production, you'll need to update your `/config.rb` so that it looks something like the following:
 
 ```ruby
 # This file is used by Rack-based servers to start the application.
@@ -546,8 +554,7 @@ Thats all there is to it! You'll now have auto-reloading in Rails, and fast requ
 
 ### The Rack Way
 
-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 using Restfulness as a standalone project, we recommend using a rack extension like [Shotgun](https://github.com/rtomayko/shotgun) to automatically reload on changes.
 
 ## Writing Tests
 
@@ -649,6 +656,7 @@ Restfulness was created by Sam Lown <me@samlown.com> as a solution for building
 The project is now awesome, thanks to contributions by:
 
  * [Adam Williams](https://github.com/awilliams)
+ * [Laura Morillo](https://github.com/lauramorillo)
 
 
 ## Caveats and TODOs
@@ -659,10 +667,20 @@ Restfulness is still a work in progress but at Cabify we are using it in product
  * Support path methods for automatic URL generation.
  * Support redirect exceptions.
  * Needs more functional testing.
- * Support for before and after filters in resources, although I'm slightly aprehensive about this.
+ * Support for before and after filters in resources, although I'm slightly apprehensive about this.
 
 ## History
 
+### 0.3.3 - January 19, 2016
+
+ * Basic support for handling large request bodies received as Tempfile (@lauramorillo)
+ * Providing human readable payload for invalid JSON.
+ * Added support for Accept and Content-Type header handling. (@samlown)
+ * Better handling of IO objects from `rack.input`, such as `Puma::NullIO`. (@samlown)
+ * Upgrading to latest version of RSpec (@samlown)
+ * Adding `request.env` accessor to Rack env (@amuino)
+ * Removing support for Ruby 1.9 (@samlown)
+
 ### 0.3.2 - February 9, 2015
 
  * Added support for application/x-www-form-urlencoded parameter decoding (@samlown)

data/lib/restfulness.rb

@@ -20,6 +20,9 @@ require "restfulness/resources/authentication"
 require "restfulness/requests/authorization"
 require "restfulness/requests/authorization_header"
 
+require "restfulness/headers/media_type"
+require "restfulness/headers/accept"
+
 require "restfulness/application"
 require "restfulness/dispatcher"
 require "restfulness/exceptions"

data/lib/restfulness/dispatchers/rack.rb

@@ -22,6 +22,7 @@ module Restfulness
 
         request = Request.new(app)
 
+        request.env        = env # Reference to Rack env
         request.uri        = rack_req.url
         request.action     = parse_action(env, rack_req.request_method)
         request.body       = rack_req.body

data/lib/restfulness/headers/accept.rb

@@ -0,0 +1,66 @@
+module Restfulness
+  module Headers
+
+    # The Accept header handler provides an array of Media Types that the
+    # client is willing to accept.
+    #
+    # Based on a simplified RFC2616 implementation, each media type is stored
+    # and ordered.
+    #
+    # Restfulness does not currently deal with the special 'q' paremeter defined
+    # in the standard as quality is not something APIs normally need to handle.
+    #
+    # Aside from media type detection, a useful feature of the accept header is to 
+    # provide the desired version of content to provide in the response. This class
+    # offers a helper method that will attempt to determine the version.
+    #
+    # Given the HTTP header:
+    #
+    #   Accept: application/com.example.api+json;version=1
+    #
+    # The resource instace has access to the version via:
+    #
+    #   request.accept.version == "1"
+    #
+    class Accept
+
+      # The -ordered- array of media types provided in the headers
+      attr_accessor :media_types
+
+      def initialize(str = "")
+        self.media_types = []
+        parse(str) unless str.empty?
+      end
+
+      def parse(str)
+        types = str.split(',').map{|t| t.strip}
+ 
+        # Attempt to crudely determine order based on length, and store
+        types.sort{|a,b| b.length <=> a.length}.each do |t|
+          media_types << MediaType.new(t)
+        end
+      end
+
+      # Request the version, always assumes that the first media type is the most relevant
+      def version
+        media_types.first.version
+      end
+
+      def json?
+        media_types.each do |mt|
+          return true if mt.json?
+        end 
+        false
+      end
+
+      def xml?
+        media_types.each do |mt|
+          return true if mt.xml?
+        end 
+        false
+      end
+
+    end
+
+  end
+end