Documenting Required Params for Rodauth Routes for JSON Requests

[Samuelodan]

Hi @janko , per our conversion earlier in Slack, I'm ready to work on documenting the routes and their required params. So, I was thinking we could use postman's documenter, but I'd like to know what you think.

BTW, these discussions are really insightful, I never even knew about them until today. I'm gonna be asking my questions here from now on so others can find them in the future.

[janko]

Postman's documenter sounds like a good idea to me 👍🏻 Will it allow hosting the API docs somewhere?

Once in the past I tried writing an OpenAPI YAML file, and I had made decent progress, but I didn't like neither the official or any other renderers. After some time has passed, I wanted to get back to finishing it, but I apparently didn't save that file anywhere unfortunately 🤷🏻‍♂️

[Samuelodan]

Alright. Here's the link https://documenter.getpostman.com/view/26686011/2s9YC7SWn9
It touches on all of the default routes.

[janko]

That looks pretty good! 👍🏻 Couple of comments:

• You probably want to use login instead of email, as that's Rodauth's default. In recent rodauth-rails versions I modified the install generator to automatically set login_param "email", as that's what Rails developers expect coming from other authentication frameworks.

• The POST /create-account endpoint also requires login-confirm when verify_account feature was not enabled.

• The Accept: application/json header is also required by default, unless you explicitly disable checking it via json_check_accept? false.

Was the goal to only document the JSON POST endpoints? Also, did you plan to eventually expand it to endpoints for non-default features?

[Samuelodan]

I'm glad you like it, thanks.

You probably want to use login instead of email

Ah, true. Thanks for the reminder. I should mention in the description that the param will be login if they use Rodauth without rodauth-rails. Or do you intend for this docs to be for Rodauth in general? I didn't really think of that. In that case, I should change it to login and mention that it could be email if they use rodauth-rails.

The POST /create-account endpoint also requires login-confirm when verify_account feature was not enabled.

Yeah, I'll go back and mention it in the descriptions for this and all the others with options. Thanks.

unless you explicitly disable checking it via json_check_accept? false.

Ah, interesting. Thanks for pointing this out, I'll mention it near the top of the docs since it applies to all requests.

Was the goal to only document the JSON POST endpoints?

Hmm. I didn't think of this too. I'm currently testing it in a Rails API app, and I guess the people that need this the most fall in the same category, so we could defer documenting the GET requests for now or make another collection (with a separate link) for those requests.
What do you think?

Also, did you plan to eventually expand it to endpoints for non-default features?

Yeah, I intend to include the other features and their POST routes. It may take a little longer since I'll have to learn to implement those and I fear that I may need the client app to be ready before I can test stuff like Omniauth. Tho I may be wrong; I hope I am.

[janko]

Or do you intend for this docs to be for Rodauth in general?

Yeah, I was imagining that this documentation would be linked from the Rodauth website directly, because there is nothing specific to rodauth-rails here, except for the recently changed login parameter. This way people using Rodauth in non-Rails projects can also stumble upon this 😉

I'm currently testing it in a Rails API app, and I guess the people that need this the most fall in the same category

Yeah, that's true, it's far more important to know param names when you're using the JSON API, in HTML mode the fields are already there and you don't really have to think about it.

It may take a little longer since I'll have to learn to implement those and I fear that I may need the client app to be ready before I can test stuff like Omniauth

I'd be curious to hear whether OmniAuth integration went well 🤞🏻 I included JSON API support in rodauth-omniauth, but haven't yet integrated it with a separate client app myself.

[Samuelodan]

I was imagining that this documentation would be linked from the Rodauth website directly...

I guess I really need to start seeing rodauth-rails as the gem that makes it much more convenient to use Rodauth in Rails apps 😅. Alright, that makes total sense. I'll make the changes and let you know again.

in HTML mode the fields are already there and you don't really have to think about it.

Yeah.

🤞🏻 I included JSON API support in rodauth-omniauth, but haven't yet integrated it with a separate client app myself.

Thanks. Yeah. I'll let you know how it goes.

Alright then. I really appreciate all the help and the opportunity to contribute in this little way. I'll keep leaving updates here until you think the documentation is ready.
Cheers!

[Samuelodan]

Hi Janko,
Sorry it took this long, but I finally made some changes to the docs and I'd love for you to take a look. Some things to be aware of though:

• The logout endpoint is missing. I'll add it next.
• I used two tables in the description of the create-account endpoint, so you could decide on which style is preferable.

I anticipate your response.
Thanks.

[Samuelodan]

Hi @janko , I think you may have missed this.

[janko]

I took a better look now, sorry for the delay, I really appreciate your work on this 🙏🏻

I like the first two-column table more, as it nicely separates param names. For me it would make sense if it included strictly required params as well, just so that you have all params in one place.

This is just a suggestion, but I think the "Condition" column would benefit by being shortened to just the boolean expression. For example, instead of

if rodauth.create_account_set_password? && rodauth.require_password_confirmation? ( true by default )

I think it would be better to have just:

create_account_set_password? && require_password_confirmation?

or maybe even use more pseudocode:

create_account_set_password? AND require_password_confirmation?

Other than compactness & DRY-ness, another reason for omitting the rodauth. is that it would cover secondary configurations e.g. rodauth(:admin) as well. As for the default values, the problem is that they depend on which features you have enabled. For example, if you enable just create_account, then require_login_confirmation? defaults to true, but if you also enable verify_account, then require_login_confirmation? defaults to false.

Other than that, everything else looks good to me 👌🏻

[Samuelodan]

No worries about the delay 🙂. I'm honored to even be discussing these things with you. Thanks for the opportunity.

I like the first two-column table more, as it nicely separates param names.
Alright, cool. I do too.

On the length of the expressions, I really like how you simplified it. I was worried about how many times the lines wrapped and how crammed it looked which led me to attempt the second table style.
Skipping rodauth. for the reason you stated makes a lot of sense to me too.

As for the default values, the problem is that they depend on which features you have enabled.
Oh wow! I didn't know this. Alright. I'll get rid of those as well.

It would be awesome if rodauth-rails could somehow generate this kinda documentation based on the the configuration. haha! 😅
Oh well. Thanks again for your time. I'll implement these changes and let you know when it's ready.

[janko]

It would be awesome if rodauth-rails could somehow generate this kinda documentation based on the the configuration. haha! 😅

Yeah, that would be amazing 💯 Like rails rodauth:routes command, but with param information as well.

[Samuelodan]

Exactly! Just like that.

[Samuelodan]

Hi Janko,
I've updated the docs with the most recent changes you suggested.

I think it's ready. What do you think?

[janko]

It looks good to me 👍🏻 Couple of small things I noticed:

• I see the tab title "Rodauth Routes Documentation", but the title on the page is "Rodaut-Rails Routes Documentation". I think it was probably meant to say "Rodauth Routes Documentation" as well.
• I see some endpoint examples using the JWT token, and some not. It would probably be good to consistently show one or the other.
• I've accidentally let the default login-confirm param in rodauth-rails, I pushed a commit to change that to email-confirm.
• The /change-login description says "It requires sending a confirmation mail to the current email address.", but that's only true if verify_login_change feature is loaded.
• There is a typo in /verify-account description: "...endpoint to verfiy the user...".
• /logout endpoint is still missing. I'm guessing other endpoints such as for MFA features would come later?

I've read somewhere that Postman supports generating docs from an OpenAPI file. I'm wondering if it works the other way around, that you can export an OpenAPI file from the docs. That would be an option for having it in version control and more easily accept contributions. This means it's also possible generate an OpenAPI file from specific Rodauth config and feed it into Postman, which could be a step closer to what we talked about.

[Samuelodan]

Hi,
Thanks for looking through and catching this much stuff.

• The page title has been fixed
• The reason for the JWT inconsistency is some of the endpoints don't require the user to be logged in, so no JWTs are sent with those requests.
• Oh, good catch. I didn't realize it was login-confirm when I was making the last changes. I just changed every login to email. haha!
• The change-login description has been edited to state that the confirmation email depends on the configuration.
• typo in verify-account description has been fixed.
• Sorry I forgot to add the logout endpoint. It has been added now. But please take a look at the description to see if it's okay. I tried to state that logout by itself doesn't revoke JWTs (which is what will likely be used with JSON requests), and that the active_sessions feature will be needed for that.

[Samuelodan]

I've read somewhere that Postman supports generating docs from a OpenAPI file.

Oh yeah, and though it doesn't support exporting to OpenAPI, I found this tool that claims to do the conversion.
This is really interesting. I'll play around with it to see how seamlessly it works.
Thanks for bringing it up.

This means it's also possible generate an OpenAPI file from specific Rodauth config and feed it into Postman, which could be a step closer to what we talked about.

Oh wow, for real? I'd love to tag along and see how you implement generating the OpenAPI file. So, essentially, a Rodauth user will get to see a tailored documentation by importing the generated file into Postman? Nice!

[janko]

The reason for the JWT inconsistency is some of the endpoints don't require the user to be logged in, so no JWTs are sent with those requests.

Oh, yeah, that makes sense 👍🏻

Couple more things I found:

• in /close-account, the title of the 2nd column was probably meant to be "Condition" instead of "Password" 🙂
• since you're mentioning the active_sessions feature in the /logout endpoint, you might also want to list the optional global_logout param for invalidating all JWT tokens for this account that active_sessions feature adds
• in /change-login, the condition still has rodauth.change_login_requires_password? instead of just change_login_requires_password

When you're ready, I would recommend making a PR to the Rodauth repo that adds a link to the API docs on the official website. I think it would be useful to link it in the rodauth-rails README as well, so that people find it more easily 🙂

[Samuelodan]

Ah, thanks for pointing those out. I was going to ask about the global_logout param.
Alright, I'll make those changes, read through again to catch any typos, and make the PRs. I'm so excited 😁.
Thank you.

[FelipeBodelon]

Thanks for setting up this great docs, tho I must admit that they were a bit too hard to find, being really useful. Maybe add them to the JSON section of the README?

I'd also suggest considering adding rodauth-omniauth and other similar JSON endpoints to it. As an example where this could be useful: I struggled with the auth/google POST endpoint, as I was sending a POST request without a body, and the server response was doing a redirect (302) instead of returning the authorize_url with a 200 status. Added an empty object to an axios request and it started working properly.

[FelipeBodelon]

Sure! I'm a bit of a one-man-team right now setting up a web application with a static React frontend and Rails backend (not fully API only yet), and betting on Rodauth, has been a breeze so far, props to Janko and other contributors.

Happy to help, so far I've implemented basic email-password routes (docs were REALLY helpful) and just now some JSON OAuth flow.

[Samuelodan]

Awesome! I think React + Rails is cool. It might be more complex than Hotwire, but I see it pop up in Rails job listings all the time.

Alright, thanks and good luck with your app. I'd love to hear about it someday.
Cheers!

[janko]

The rodauth-omniauth README already has a JSON section that shows examples of JSON requests. The only thing that's required is Content-Type: application/json, body can be empty. Maybe axios sets Content-Type: application/json only when you pass it a body object 🤷🏻‍♂️

[FelipeBodelon]

I think this check must definitely be it, and the source of some of my issues. I can get around the issue for the POST request, but for the GET /auth/github/callback request I think "Content-Type" headers are never included, and rightly so as it is describing content that a GET request doesn't include. Maybe Axios strips them and other methods could include the Header anyways, but considering the standard I think a Content-Type check is invalid for GET requests.

This is clearly an issue as I was getting redirected for the GET request too, and this time there is no body to include an empty json :(
Tried with a json_only? true flag and the request returns 200 , and 500 when failing as expected per the docs. Can't really maintain a json_only behaviour yet so I'll try to force include the header if possible.

BTW this is a cool set of libraries. As a Ruby/Rails noobie, thanks for your quick response. You'll be hearing more from me as I was witting up a discussion thread for a CORS issue I encountered.

Edit: Is this a Rails/Rack thing or is the check being done by rodauth-rails/omniauth? It seems like the axios maintainers agree with this logic as they closed this related issue, I agree that it's more of an api design issue over wrong standards usage.

[janko]

Reading the axios issue, it sounds like Rodauth probably should also check the Accept request header in #json_request?, maybe return true if either Content-Type or Accept are application/json. However, Rodauth also doesn't officially support GET requests in JSON mode.

It just came to my mind, what if you used POST /auth/github/callback instead of GET? I thought that GET was somehow hardcoded into OmniAuth, but I couldn't find any proof of that. And it seems I used POST for the JSON tests for rodauth-omniauth. The only difference is the parameters you'd normally pass via the query string would need to be passed in the request body as JSON, but axios should automatically take care of that for you.

If you verify that this works, I'll update the README. POST would make more sense than GET either way, since the callback route typically has side-effects such as logging the user in. GET only makes sense in the classic redirect scenario in HTML mode.