From 19ea91837f34afb28cc4184dce801ed328e92125 Mon Sep 17 00:00:00 2001
From: Joe Marty <jmarty@iexposure.com>
Date: Tue, 14 Feb 2017 16:51:14 -0600
Subject: [PATCH 1/2] Document how to add session middleware back

Without this, it's not clear that session middleware has special cases to handle with the `api_only` flag
---
 guides/source/api_app.md | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/guides/source/api_app.md b/guides/source/api_app.md
index f373d313cc..f73c9022bc 100644
--- a/guides/source/api_app.md
+++ b/guides/source/api_app.md
@@ -332,6 +332,28 @@ will be:
 { :person => { :firstName => "Yehuda", :lastName => "Katz" } }
 ```
 
+### Using Session Middlewares
+The following middlewares are (by default) included for session management.  If one of your API clients is a browser, you might want to add one of these back in:
+- `ActionDispatch::Session::CacheStore`
+- `ActionDispatch::Session::CookieStore`
+- `ActionDispatch::Session::MemCacheStore`
+
+The trick to adding these back in is that, by default, they are passed `session_options`
+when added (including the session key), so you can't just add a `session_store.rb` initializer, add
+`use ActionDispatch::Session::CookieStore` and have sessions functioning as normal.
+
+To be clear: sessions may work, but your session options will be ignored (i.e the session key will default
+to `_session_id`).  Instead of the initializer, you'll have to set the relevant options somewhere
+before your middleware is built (like `application.rb`) and pass them to your prefered middleware,
+like this:
+
+**application.rb:**
+```ruby
+config.session_store :cookie_store, key: '_interslice_session'
+config.middleware.use ActionDispatch::Cookies # Required for all session management
+config.middleware.use ActionDispatch::Session::CookieStore, config.session_options
+```
+
 ### Other Middleware
 
 Rails ships with a number of other middleware that you might want to use in an
@@ -340,10 +362,6 @@ API application, especially if one of your API clients is the browser:
 - `Rack::MethodOverride`
 - `ActionDispatch::Cookies`
 - `ActionDispatch::Flash`
-- For session management
-    * `ActionDispatch::Session::CacheStore`
-    * `ActionDispatch::Session::CookieStore`
-    * `ActionDispatch::Session::MemCacheStore`
 
 Any of these middleware can be added via:
 

From 3376ab8055eebd865c2a373df46d4ae67ee54856 Mon Sep 17 00:00:00 2001
From: Joe Marty <joe.marty@smartersorting.com>
Date: Thu, 26 Dec 2019 09:25:47 -0600
Subject: [PATCH 2/2] Clarify session management middleware sections

Addresses some comments in original PR for docs on using session management middleware in API apps
---
 guides/source/api_app.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/guides/source/api_app.md b/guides/source/api_app.md
index f73c9022bc..dbee5bf069 100644
--- a/guides/source/api_app.md
+++ b/guides/source/api_app.md
@@ -333,25 +333,24 @@ will be:
 ```
 
 ### Using Session Middlewares
-The following middlewares are (by default) included for session management.  If one of your API clients is a browser, you might want to add one of these back in:
+The following middlewares, used for session management, are excluded from API apps since they normally don't need sessions.  If one of your API clients is a browser, you might want to add one of these back in:
 - `ActionDispatch::Session::CacheStore`
 - `ActionDispatch::Session::CookieStore`
 - `ActionDispatch::Session::MemCacheStore`
 
 The trick to adding these back in is that, by default, they are passed `session_options`
 when added (including the session key), so you can't just add a `session_store.rb` initializer, add
-`use ActionDispatch::Session::CookieStore` and have sessions functioning as normal.
+`use ActionDispatch::Session::CookieStore` and have sessions functioning as usual.  (To be clear: sessions
+may work, but your session options will be ignored - i.e the session key will default to `_session_id`)
 
-To be clear: sessions may work, but your session options will be ignored (i.e the session key will default
-to `_session_id`).  Instead of the initializer, you'll have to set the relevant options somewhere
-before your middleware is built (like `application.rb`) and pass them to your prefered middleware,
-like this:
+Instead of the initializer, you'll have to set the relevant options somewhere before your middleware is
+built (like `application.rb`) and pass them to your prefered middleware, like this:
 
 **application.rb:**
 ```ruby
-config.session_store :cookie_store, key: '_interslice_session'
-config.middleware.use ActionDispatch::Cookies # Required for all session management
-config.middleware.use ActionDispatch::Session::CookieStore, config.session_options
+config.session_store :cookie_store, key: '_interslice_session' # <-- this also configures session_options for use below
+config.middleware.use ActionDispatch::Cookies # Required for all session management (regardless of session_store)
+config.middleware.use config.session_store, config.session_options
 ```
 
 ### Other Middleware