Permalink
Browse files

Add brief introduction to REST to the resources documentation. Closes #…

…8100. [fearoffish]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6681 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent 4e51123 commit 06cd7b0906c0b6c7c7e60ee329439ae694744134 Marcel Molina committed May 6, 2007
Showing with 40 additions and 0 deletions.
  1. +2 −0 actionpack/CHANGELOG
  2. +38 −0 actionpack/lib/action_controller/resources.rb
View
2 actionpack/CHANGELOG
@@ -1,5 +1,7 @@
*SVN*
+* Add brief introduction to REST to the resources documentation. [fearoffish]
+
* Fix various documentation typos throughout ActionPack. [Henrik N]
* Enhance documentation and add examples for url_for. [jeremymcanally]
View
38 actionpack/lib/action_controller/resources.rb
@@ -1,4 +1,42 @@
module ActionController
+ # == Overview
+ #
+ # ActionController::Resources are a way of defining RESTful resources. A RESTful resource, in basic terms,
+ # is something that can be pointed at and it will respond with a representation of the data requested.
+ # In real terms this could mean a user with a browser requests an HTML page, or that a desktop application
+ # requests XML data.
+ #
+ # RESTful design is based on the assumption that there are four generic verbs that a user of an
+ # application can request from a resource (the noun).
+ #
+ # Resources can be requested using four basic HTTP verbs (GET, POST, PUT, DELETE), the method used
+ # denotes the type of action that should take place.
+ #
+ # === The Different Methods and their Usage
+ #
+ # +GET+ Requests for a resource, no saving or editing of a resource should occur in a GET request
+ # +POST+ Creation of resources
+ # +PUT+ Editing of attributes on a resource
+ # +DELETE+ Deletion of a resource
+ #
+ # === Examples
+ #
+ # # A GET request on the Posts resource is asking for all Posts
+ # GET /posts
+ # # A GET request on a single Post resource is asking for that particular Post
+ # GET /posts/1
+ # # A POST request on the Posts resource is asking for a Post to be created with the supplied details
+ # POST /posts # with => { :title => "My Whizzy New Post", :body => "I've got a brand new combine harvester" }
+ # # A PUT request on a single Post resource is asking for a Post to be updated
+ # POST /posts # with => { :id => 1, :title => "Changed Whizzy Title" }
+ # # A DELETE request on a single Post resource is asking for it to be deleted
+ # DELETE /posts # with => { :id => 1 }
+ #
+ # By using the REST convention, users of our application can assume certain things about how the data
+ # is requested and how it is returned. Rails simplifies the routing part of RESTful design by
+ # supplying you with methods to create them in your routes.rb file.
+ #
+ # Read more about REST at http://en.wikipedia.org/wiki/Representational_State_Transfer
module Resources
class Resource #:nodoc:
attr_reader :collection_methods, :member_methods, :new_methods

0 comments on commit 06cd7b0

Please sign in to comment.