1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00

Docs review of api_app.md

Pass through correcting api_app.md. The list of included modules and
middleware was tested through a sample API app, and was listed in the
same order an end user would see in their terminal.

[ci skip]
This commit is contained in:
Jon Moss 2016-01-28 17:56:51 -05:00
parent ee9d479941
commit 3745d5430b

View file

@ -44,11 +44,11 @@ using Rails is: "isn't using Rails to spit out some JSON overkill? Shouldn't I
just use something like Sinatra?". just use something like Sinatra?".
For very simple APIs, this may be true. However, even in very HTML-heavy For very simple APIs, this may be true. However, even in very HTML-heavy
applications, most of an application's logic is actually outside of the view applications, most of an application's logic lives outside of the view
layer. layer.
The reason most people use Rails is that it provides a set of defaults that The reason most people use Rails is that it provides a set of defaults that
allows us to get up and running quickly without having to make a lot of trivial allows developers to get up and running quickly, without having to make a lot of trivial
decisions. decisions.
Let's take a look at some of the things that Rails provides out of the box that are Let's take a look at some of the things that Rails provides out of the box that are
@ -97,7 +97,7 @@ Handled at the Action Pack layer:
means not having to spend time thinking about how to model your API in terms means not having to spend time thinking about how to model your API in terms
of HTTP. of HTTP.
- URL Generation: The flip side of routing is URL generation. A good API based - URL Generation: The flip side of routing is URL generation. A good API based
on HTTP includes URLs (see [the GitHub gist API](http://developer.github.com/v3/gists/) on HTTP includes URLs (see [the GitHub Gist API](http://developer.github.com/v3/gists/)
for an example). for an example).
- Header and Redirection Responses: `head :no_content` and - Header and Redirection Responses: `head :no_content` and
`redirect_to user_url(current_user)` come in handy. Sure, you could manually `redirect_to user_url(current_user)` come in handy. Sure, you could manually
@ -126,7 +126,7 @@ when configuring Active Record.
**The short version is**: you may not have thought about which parts of Rails **The short version is**: you may not have thought about which parts of Rails
are still applicable even if you remove the view layer, but the answer turns out are still applicable even if you remove the view layer, but the answer turns out
to be "most of it". to be most of it.
The Basic Configuration The Basic Configuration
----------------------- -----------------------
@ -192,10 +192,11 @@ An API application comes with the following middleware by default:
- `Rack::Sendfile` - `Rack::Sendfile`
- `ActionDispatch::Static` - `ActionDispatch::Static`
- `ActionDispatch::LoadInterlock`
- `ActiveSupport::Cache::Strategy::LocalCache::Middleware` - `ActiveSupport::Cache::Strategy::LocalCache::Middleware`
- `Rack::Runtime`
- `ActionDispatch::RequestId` - `ActionDispatch::RequestId`
- `Rails::Rack::Logger` - `Rails::Rack::Logger`
- `Rack::Runtime`
- `ActionDispatch::ShowExceptions` - `ActionDispatch::ShowExceptions`
- `ActionDispatch::DebugExceptions` - `ActionDispatch::DebugExceptions`
- `ActionDispatch::RemoteIp` - `ActionDispatch::RemoteIp`
@ -323,7 +324,7 @@ will be:
{ :person => { :firstName => "Yehuda", :lastName => "Katz" } } { :person => { :firstName => "Yehuda", :lastName => "Katz" } }
``` ```
### Other Middlewares ### Other Middleware
Rails ships with a number of other middleware that you might want to use in an Rails ships with a number of other middleware that you might want to use in an
API application, especially if one of your API clients is the browser: API application, especially if one of your API clients is the browser:
@ -360,22 +361,24 @@ Choosing Controller Modules
An API application (using `ActionController::API`) comes with the following An API application (using `ActionController::API`) comes with the following
controller modules by default: controller modules by default:
- `ActionController::UrlFor`: Makes `url_for` and friends available. - `ActionController::UrlFor`: Makes `url_for` and similar helpers available.
- `ActionController::Redirecting`: Support for `redirect_to`. - `ActionController::Redirecting`: Support for `redirect_to`.
- `ActionController::Rendering`: Basic support for rendering. - `AbstractController::Rendering` and `ActionController::ApiRendering`: Basic support for rendering.
- `ActionController::Renderers::All`: Support for `render :json` and friends. - `ActionController::Renderers::All`: Support for `render :json` and friends.
- `ActionController::ConditionalGet`: Support for `stale?`. - `ActionController::ConditionalGet`: Support for `stale?`.
- `ActionController::ForceSSL`: Support for `force_ssl`.
- `ActionController::DataStreaming`: Support for `send_file` and `send_data`.
- `AbstractController::Callbacks`: Support for `before_action` and friends.
- `ActionController::Instrumentation`: Support for the instrumentation
hooks defined by Action Controller (see [the instrumentation
guide](active_support_instrumentation.html#action-controller)).
- `ActionController::Rescue`: Support for `rescue_from`.
- `ActionController::BasicImplicitRender`: Makes sure to return an empty response - `ActionController::BasicImplicitRender`: Makes sure to return an empty response
if there's not an explicit one. if there's not an explicit one.
- `ActionController::StrongParameters`: Support for parameters white-listing in - `ActionController::StrongParameters`: Support for parameters white-listing in
combination with Active Model mass assignment. combination with Active Model mass assignment.
- `ActionController::ForceSSL`: Support for `force_ssl`.
- `ActionController::DataStreaming`: Support for `send_file` and `send_data`.
- `AbstractController::Callbacks`: Support for `before_action` and
similar helpers.
- `ActionController::Rescue`: Support for `rescue_from`.
- `ActionController::Instrumentation`: Support for the instrumentation
hooks defined by Action Controller (see [the instrumentation
guide](active_support_instrumentation.html#action-controller) for
more information regarding this).
- `ActionController::ParamsWrapper`: Wraps the parameters hash into a nested hash - `ActionController::ParamsWrapper`: Wraps the parameters hash into a nested hash
so you don't have to specify root elements sending POST requests for instance. so you don't have to specify root elements sending POST requests for instance.
@ -404,5 +407,5 @@ Some common modules you might want to add:
- `ActionController::Cookies`: Support for `cookies`, which includes - `ActionController::Cookies`: Support for `cookies`, which includes
support for signed and encrypted cookies. This requires the cookies middleware. support for signed and encrypted cookies. This requires the cookies middleware.
The best place to add a module is in your `ApplicationController` but you can The best place to add a module is in your `ApplicationController`, but you can
also add modules to individual controllers. also add modules to individual controllers.