Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

better documentation for the url #395

Closed
wibeasley opened this issue Jun 13, 2022 · 4 comments
Closed

better documentation for the url #395

wibeasley opened this issue Jun 13, 2022 · 4 comments
Assignees

Comments

@wibeasley
Copy link
Member

inspired by #394, the REDCapR package should throw a better error message when passed a bad URL to a REDCap server. It probably goes in https://github.com/OuhscBbmc/REDCapR/blob/main/R/kernel-api.R.

Maybe I can better parse the curl or httr error message. If that's not possible, maybe I include a separate call just to the server to check for a response. Adding a round-trip server call isn't the optimal performance decision, but that's gotta be small and the tradeoff is worth the improved usability.

@sutzig
Copy link

sutzig commented Jun 13, 2022

Thank you @wibeasley. My experience was a misunderstanding of what was required for a complete/valid URI. I don't know if all API calls end with or include the string "api", but, if that's the case, perhaps this could be reflected in the documentation and a function to check that the value entered for the redcap_uri ends with or include "api". My error was using only "https://server.org/" rather than "https://server.org/apps/redcap/api/" I was able to identify my error by going to the API Playground section of the RedCap project, which may another resource to call out in the documentation.

@wibeasley
Copy link
Member Author

  1. Sure, I can do that with a regex like ^.+?/api/?$, which wouldn't cost a round trip to the server
  2. Maybe it could be a warning (not an error) in case someone is doing something unconventional redirecting paths.
  3. Is there anything you'd change/add to redcap_read()'s documentation, and its examples below?

@sutzig
Copy link

sutzig commented Jun 13, 2022

I guess I would more explicitly call out the expected URI syntax in the redcap_uri argument description (i.e. "The URI (uniform resource identifier) of the REDCap project API generally formatted as https://server.org/apps/redcap/api/. Required.") and/or create a more explicitly focused redcap_read example highlighting the expect URI syntax. The example didn't seem to apply to my issue when I first reviewed it since I wasn't trying to specify column types.

@wibeasley wibeasley changed the title better error message if a bad url is passed better documentation for the url Aug 12, 2022
@wibeasley
Copy link
Member Author

wibeasley commented Aug 12, 2022

Ok, in that case I'll chicken out and not test the url. But as you suggested, provide a better example of the url.

I updated the documentation of each function that uses the parameter. I also added this entry to the troubleshooting guide.


  1. Is the URL/URI correct? Notice the url typically resembles https://bbmc.ouhsc.edu/redcap/api/ and not https://bbmc.ouhsc.edu/ (even if https://bbmc.ouhsc.edu/ redirects to https://bbmc.ouhsc.edu/redcap).

wibeasley added a commit that referenced this issue Aug 15, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants