Documentation: Details/Notes regarding Rails API-only applications

[colinross]

This is a bit of a knock on PR related to #4947 specifically addressing documentation.

I have been experimenting more and more with rails api-only application leveraging devise this PR attempts to make a solid attempt to stem the documentation issues (or really lack thereof) from creating unnecessary noise as bugs or feature requests.

[sourcelevel-bot]

Hello, @colinross! This is your first Pull Request that will be reviewed by SourceLevel, an automatic Code Review service. It will leave comments on this diff with potential issues and style violations found in the code as you push new commits. You can also see all the issues found on this Pull Request on its review page. Please check our documentation for more information.

[colinross]

I'm not quite sure how to best add this point to the documentation, but there is a slight, nuanced difference between an Rails API-only Application and an application where your resources (the protected controllers for instance) are extending from ActionController::API. In comes down to which controller type your devise parent controller (ApplicationController by default) extends from.

While outside the scope of this documentation PR, I wonder if the better way to 'address supporting' API controllers would be to issue warnings when known incompatibilities are loaded/used. e.g.
Rails.logger "Rememberable is not compatible with controllers extending from ActionController::API; Either disable/remove the :rememberable module in the model's configuration or extend from ActionController::Base"

[mracos]

Nice job @colinross! 💙
I left a couple of comments, let me know wdyt about them. 😄

[colinross]

Those edits are fine. Thanks for the time.

[mracos]

Just a couple of nits them we are good to go!

[colinross]

Ahh, good catch

[mracos]

Thanks for your contribution @colinross. 💙

About incompatibilities between some features of devise and ActionController::API I think a good start is to map some of them (you already mentioned rememberable).

With that info, we can then decide the best course of action for each one, which could be to raise a warning as you said or even just documenting it somewhere. The point is that we would need to have this somehow mapped.

Makes sense to you?

[colinross]

That makes sense to me. I'll see what I can get started on and get a PR in the near future. I'm seeing maybe a table of 'Feature/Module' with Supported Y/N and a place to detail the caveats? I'm pretty sure Omniauth will have a caveat or two.

Maybe a FEATURE_SUPPORT.md file? Not sure if i want to muddy up the already quite extensive README.md

[mracos]

WDYT about starting with a wiki article and then later we decide where to put it?

[colinross]

Sure.

…

On Tue, Oct 29, 2019 at 11:59 AM Marcos Ferreira ***@***.***> wrote: WDYT about starting with a wiki article and then later we decide where to put it? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5152>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABNFTZWSLYDOEZEJUIRCQTQRCBYFANCNFSM4I7SM7YQ> .

[colinross]

Started a wiki entry

https://github.com/plataformatec/devise/wiki/API-Mode-Compatibility-Guide