From 6b28c94e20800e6be10b4f7dadff55c3c55f44ce Mon Sep 17 00:00:00 2001 From: Carlos Antonio da Silva Date: Tue, 6 Mar 2012 08:26:09 -0300 Subject: [PATCH] Add some docs for MiddlewareStackProxy methods and api_only! [Carlos Antonio da Silva & Santiago Pastorino] --- railties/guides/source/api_app.textile | 5 ++- railties/guides/source/configuring.textile | 8 +++++ railties/lib/rails/configuration.rb | 41 ++++++++++++++++++++-- 3 files changed, 49 insertions(+), 5 deletions(-) diff --git a/railties/guides/source/api_app.textile b/railties/guides/source/api_app.textile index f2d00c5768..258696385f 100644 --- a/railties/guides/source/api_app.textile +++ b/railties/guides/source/api_app.textile @@ -13,15 +13,14 @@ endprologue. h3. What is an API app? -Traditionally, when people said that they used Rails as an "API", they meant -providing a programmatically accessible API alongside their web application. +Traditionally, when people said that they used Rails as an "API", they meant providing a programmatically accessible API alongside their web application. For example, GitHub provides "an API":http://developer.github.com that you can use from your own custom clients. With the advent of client-side frameworks, more developers are using Rails to build a backend that is shared between their web application and other native applications. For example, Twitter uses its "public API":https://dev.twitter.com in its web application, which is built as a static site that consumes JSON resources. -Instead of using Rails to generate dynamic HTML that will communicate with the server through forms and links, many developers are treating their web application as just another client, delivered as static HTML, CSS and JavaScript, and consuming a simple JSON API +Instead of using Rails to generate dynamic HTML that will communicate with the server through forms and links, many developers are treating their web application as just another client, delivered as static HTML, CSS and JavaScript, and consuming a simple JSON API This guide covers building a Rails application that serves JSON resources to an API client *or* client-side framework. diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile index 0ab1076fff..d72ff57dc5 100644 --- a/railties/guides/source/configuring.textile +++ b/railties/guides/source/configuring.textile @@ -248,6 +248,14 @@ They can also be removed from the stack completely: config.middleware.delete ActionDispatch::BestStandardsSupport +In addition to these methods to handle the stack, if your application is going to be used as an API endpoint only, the middleware stack can be configured like this: + + +config.middleware.api_only! + + +By doing this, Rails will create a smaller middleware stack, by not adding some middlewares that are usually useful for browser access only, such as Cookies, Session and Flash, BestStandardsSupport, and MethodOverride. You can always add any of them later manually if you want. Refer to the "API App docs":api_app.html for more info on how to setup your application for API only apps. + h4. Configuring i18n * +config.i18n.default_locale+ sets the default locale of an application used for i18n. Defaults to +:en+. diff --git a/railties/lib/rails/configuration.rb b/railties/lib/rails/configuration.rb index 0efa21d82c..d3032bb8dd 100644 --- a/railties/lib/rails/configuration.rb +++ b/railties/lib/rails/configuration.rb @@ -6,7 +6,44 @@ require 'rails/rack' module Rails module Configuration - class MiddlewareStackProxy #:nodoc: + # MiddlewareStackProxy is a proxy for the Rails middleware stack that allows + # you to configure middlewares in your application. It works basically as a + # command recorder, saving each command to be applied after initialization + # over the default middleware stack, so you can add, swap, or remove any + # middleware in Rails. + # + # You can add your own middlewares by using the +config.middleware.use+ method: + # + # config.middleware.use Magical::Unicorns + # + # This will put the +Magical::Unicorns+ middleware on the end of the stack. + # You can use +insert_before+ if you wish to add a middleware before another: + # + # config.middleware.insert_before ActionDispatch::Head, Magical::Unicorns + # + # There's also +insert_after+ which will insert a middleware after another: + # + # config.middleware.insert_after ActionDispatch::Head, Magical::Unicorns + # + # Middlewares can also be completely swapped out and replaced with others: + # + # config.middleware.swap ActionDispatch::BestStandardsSupport, Magical::Unicorns + # + # And finally they can also be removed from the stack completely: + # + # config.middleware.delete ActionDispatch::BestStandardsSupport + # + # In addition to these methods to handle the stack, if your application is + # going to be used as an API endpoint only, the middleware stack can be + # configured like this: + # + # config.middleware.api_only! + # + # By doing this, Rails will create a smaller middleware stack, by not adding + # some middlewares that are usually useful for browser access only, such as + # Cookies, Session and Flash, BestStandardsSupport, and MethodOverride. You + # can always add any of them later manually if you want. + class MiddlewareStackProxy def initialize @operations = [] @api_only = false @@ -41,7 +78,7 @@ module Rails @operations << [:delete, args, block] end - def merge_into(other) + def merge_into(other) #:nodoc: @operations.each do |operation, args, block| other.send(operation, *args, &block) end