The document discusses REST (Representational State Transfer) and how it is implemented in Rails. Key points:
- Resources are represented as unique URLs and operations are mapped to HTTP methods like GET, POST, PUT, DELETE.
- Rails provides convenience for building RESTful APIs through routes like map.resources which generates RESTful routes for a resource.
- Additional options allow customizing the routes generated, adding member or collection routes, and handling non-standard URI patterns.
2. What is REST? The REST style characterizes communication between system components (where a component is, say, a web browser or a server) as a series of requests to which the responses are representations of resources. What you actually do get hold of is never the resource itself, but a representation of it. A resource may, at any given point, be available in any number of representations.
3. Resources as URLs A resource is something like a "business entity" in modeling lingo. It's an entity you wish to expose as part of an API. Almost always, the entity is a noun, e.g. a person, a car, or a football match. Each resource is represented as a unique URL.
6. Services should be stateless An objective of REST is to be able to switch clients at any time and receive the same result. So are cookies used at all? Yes, cookies can be used, but mainly for authentication. They should only affect if the user can make a call, but not how the server responds.
7. Services should be idempotent "Idempotent" means that once you pass a message to service, there's no additional effect of passing the same message again.
8. Benefits of Rails’REST Convenience and automatic best practices for you A REST interface to your application’s services, for everyone else
9. A Short Notice There’s a temptation to call your actions add_item and replace_email_address and things like that. But things get simpler when you name your actions after CRUD operations, or as close to the names of those operations as you can get.
10. map.resources :books You will have created four named routes and allow you to connect to seven controller actions. In most cases, is that they have created a Book model, a book controller with a set of CRUD actions, and some named routes pertaining to that controller (courtesy of map.resources :books ).
11. :only, :except Each of routes generated by map.resources takes up memory in your application, and causes Rails to generate additional routing logic. Luckily, since Rails 2.2 you can use the :only and :except options to fine-tune the routes that Rails will generate for resources. You can supply a single action, an array of actions, or the special :all or :none options.
13. PUT and DELETE A PUT or DELETE request, in the context of REST in Rails, is actually a POST request with a hidden field called _method set to either “put” or “delete”. The Rails application processing the request will pick up on this, and route the request appropriately to the update or destroy action.
14. Allows you to introspect all of the routes your application recognizes. rake routes command
15. map.resource Imagine, for instance, that you have a resource that could exist only one, a blog. You don’t need an index action for the blog resource, since there is only (and can only ever be) one blog in the application. map.resource is designed for just this situation. You use it in just the same way as its plural relative.
17. map.namespace In some cases—administration interfaces, for instance—you may need to namespace a resource without actually nesting it under another. For example: /admin/posts map.namespace :admin do |admin| map.resources :posts end
18. Nested Resources /auctions/1/bids/5 map.resources :auctions do |auction| auction.resources :bids end auction_bids_url, auction_bids_path, new_auction_bid_url, edit_auction_bid_url Whenever you use the user named routes, you will provide a group, resource in which they can be nested.
19. Nested Resources <%= link_to “See all bids”, auction_bids_path(@auction) %> <%= link_to “Delete this bid”, auction_bid_path(@auction, @bid), :method => :delete %> You can nest to any depth. Each level of nesting adds one to the number of arguments you have to supply to the nested routes.
20. Deep Nesting? Resources should never be nested more than one level deep. map.resources :auctions do |auctions| auctions.resources :bids do |bids| bids.resources :comments end end
21. Deep Nesting? (cont.) map.resources :auctions do |auctions| auctions.resources :bids end map.resources :bids do |bids| bids.resources :comments end map.resources :comments auctions_path # /auctions auctions_path(1) # /auctions/1 auction_bids_path(1) # /auctions/1/bids bid_path(2) # /bids/2 bid_comments_path(3) # /bids/3/comments comment_path(4) # /comments/4
22. :path_prefix map.resources :auctions map.resources :bids, :path_prefix => “auctions/:auction_id” What you’re saying here is that you want all of the bids URLs to include the static string “auctions” and a value for auction_id . The main difference has to do with the naming of the helper methods that are generated. Nested resources automatically get a name prefix corresponding to their parent resource.
23. : name_prefix /auctions/2/bids/5 /auctions/5 map.resources :auctions do |auction| auction.resources :bids, :name_prefix => nil end auction_path(@auction, @bid) auction_path(@auction)
24. RESTful Controllers It was just presented as something that happens automatically, which in fact it does, based on the name of the resource. map.resources :auctions do |auction| auction.resources :bids end Having the option means you can name the (userfacing) resource whatever you want, and keep the name of your controller aligned with different naming standards map.resources :my_auctions, :controller => :auctions do |auction| auction.resources :my_bids, :controller => :bids end
25. Extra Member Routes For example, let’s say we want to make it possible to retract a bid. map.resources :auctions do |auction| auction.resources :bids end retract_bid_url map.resources :auctions do |a| a.resources :bids, :member => {:retract => :any} end
26. Extra Collection Routes You can also use this routing technique to add routes that conceptually apply to an entire collection of resources map.resources :auctions, :collection => { :terminate => :any }
27. Doing it yourself There are two main circumstances when you might want to hand-code your RESTful routes instead of using the macros: when your application does not expose the full set of actions, and when your URIs follow a nonstandard pattern.