Merge pull request #176 from cmu-delphi/docs/options

Better document API keys

Author: dshemetov

NAMESPACE

@@ -15,7 +15,7 @@ export(disable_cache)
 export(epirange)
 export(fetch)
 export(fetch_args_list)
-export(get_auth_key)
+export(get_api_key)
 export(pub_covid_hosp_facility)
 export(pub_covid_hosp_facility_lookup)
 export(pub_covid_hosp_state_timeseries)
@@ -44,6 +44,7 @@ export(pvt_norostat)
 export(pvt_quidel)
 export(pvt_sensors)
 export(pvt_twitter)
+export(set_api_key)
 export(set_cache)
 import(cachem)
 import(glue)

R/auth.R

@@ -1,36 +1,71 @@
-#' Getting the API key
+#' Get and set API keys
 #'
-#' @description
-#' Get the API key from the environment variable `DELPHI_EPIDATA_KEY` or
-#' `getOption("delphi.epidata.key")`.
+#' Get and set the API key used to make requests to the Epidata API. Without a
+#' key, requests may be subject to rate limits and other limitations.
 #'
-#' @return The API key as a string or "".
+#' We recommend you register for an API key. While most endpoints are available
+#' without one, there are [limits on API usage for anonymous
+#' users](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html),
+#' including a rate limit. If you regularly request large amounts of data,
+#' please consider [registering for an API
+#' key](https://api.delphi.cmu.edu/epidata/admin/registration_form).
 #'
+#' API keys are strings and can be set in two ways. If the environment variable
+#' `DELPHI_EPIDATA_KEY` is set, it will be used automatically. Environment
+#' variables can be set either in the shell or by editing your `.Renviron` file,
+#' which will ensure the setting applies to all R sessions. See `?Startup` for a
+#' description of `Renviron` files and where they can be placed.
+#'
+#' Alternately, the API key can be set from within a session by using
+#' `set_api_key()`, which sets the R option `delphi.epidata.key` using
+#' `options()`. If this option is set, it is used in preference to the
+#' environment variable, so you may change keys within an R session. R options
+#' are not preserved between sessions, so `set_api_key()` must be run every time
+#' you open R. Alternately, you can have R set the option at startup by adding
+#' it to your `.Rprofile`; see `?Startup` for a description of `Rprofile` files
+#' and where they can be placed.
+#'
+#' Once an API key is set, it is automatically used for all requests made by
+#' functions in this package.
+#'
+#' @return For `get_api_key()`, returns the current API key as a string, or
+#'   `""` if none is set.
+#'
+#' @seealso [usethis::edit_r_environ()] to automatically edit the `.Renviron`
+#'   file; [usethis::edit_r_profile()] to automatically edit the `.Rprofile`
+#'   file
+#'
+#' @references Delphi Epidata API Keys documentation.
+#'   <https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html>
+#'
+#' Delphi Epidata API Registration Form.
+#' <https://api.delphi.cmu.edu/epidata/admin/registration_form>
 #' @export
-get_auth_key <- function() {
-  key <- Sys.getenv("DELPHI_EPIDATA_KEY", unset = "")
+get_api_key <- function() {
+  key <- getOption("delphi.epidata.key", default = "")
   if (key != "") {
     return(key)
   }
 
-  key <- getOption("delphi.epidata.key", default = "")
+  key <- Sys.getenv("DELPHI_EPIDATA_KEY", unset = "")
   if (key != "") {
     return(key)
   }
 
   cli::cli_warn(
     c(
-      "No API key found. You will be limited to non-complex queries and encounter rate limits if you proceed.
-      To avoid this, you can get your key by registering
-      at https://api.delphi.cmu.edu/epidata/admin/registration_form and then:",
-      "i" = "set the environment variable DELPHI_EPIDATA_KEY",
-      "i" = "set the option 'delphi.epidata.key'",
-      "",
-      "To save your key for later sessions (and hide it from your code), you can edit your .Renviron file with:",
-      "i" = "usethis::edit_r_environ()"
+      "No API key found. You will be limited to non-complex queries and encounter rate limits if you proceed.",
+      "i" = "See {.help set_api_key} for details on obtaining and setting API keys."
     ),
     .frequency = "regularly",
     .frequency_id = "delphi.epidata.key"
   )
   return("")
 }
+
+#' @rdname get_api_key
+#' @param key API key to use for future requests
+#' @export
+set_api_key <- function(key) {
+  options(delphi.epidata.key = key)
+}

R/epidatr-package.R

@@ -1,3 +1,8 @@
+#' @section Package options:
+#'
+#' The `delphi.epidata.key` option specifies the API key to be used when making
+#' requests to the Epidata API.
+#'
 #' @keywords internal
 #' @include cache.R
 "_PACKAGE"

R/request.R

@@ -29,7 +29,7 @@ do_request <- function(url, params, timeout_seconds = 30) {
     query = params,
     terminate_on = c(400, 401, 403, 405, 414, 500),
     http_headers,
-    httr::authenticate("epidata", get_auth_key()),
+    httr::authenticate("epidata", get_api_key()),
     httr::timeout(timeout_seconds)
   )
   if (res$status_code == 414) {
@@ -39,7 +39,7 @@ do_request <- function(url, params, timeout_seconds = 30) {
       encode = "form",
       terminate_on = c(400, 401, 403, 405, 414, 500),
       http_headers,
-      httr::authenticate("epidata", get_auth_key())
+      httr::authenticate("epidata", get_api_key())
     )
   }
   res

README.Rmd

@@ -79,14 +79,12 @@ The Delphi API requires a (free) API key for full functionality. To generate
 your key, register for a pseudo-anonymous account
 [here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and see more
 discussion on the [general API
-website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). The
-`epidatr` client will automatically look for this key in the R option
-`delphi.epidata.key` or in the environment variable
-`DELPHI_EPIDATA_KEY`. We recommend storing your key in `.Renviron` file, which R
-will read by default.
-
-Note that for the time being, the private endpoints (i.e. those prefixed with
-`pvt`) will require a separate key that needs to be passed as an argument.
+website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). See the
+`set_api_key()` function documentation for details on how to use your API key.
+
+Note that the private endpoints (i.e. those prefixed with `pvt_`) require a
+separate key that needs to be passed as an argument. These endpoints require
+specific data use agreements to access.
 
 [mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg
 [mit-url]: https://opensource.org/license/mit/

README.md

@@ -17,8 +17,8 @@ provides real-time access to epidemiological surveillance data for
 influenza, COVID-19, and other diseases for the USA at various
 geographical resolutions, both from official government sources such as
 the [Center for Disease Control
-(CDC)](https://www.cdc.gov/datastatistics/index.html), public sources such as [Google
-Trends](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/google-symptoms.html),
+(CDC)](https://www.cdc.gov/datastatistics/index.html) and [Google
+Trends](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/google-symptoms.html)
 and private partners such as
 [Facebook](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/)
 and [Change Healthcare](https://www.changehealthcare.com/). It is built
@@ -104,14 +104,12 @@ generate your key, register for a pseudo-anonymous account
 [here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and
 see more discussion on the [general API
 website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html).
-The `epidatr` client will automatically look for this key in the R
-option `delphi.epidata.key` or in the environment variable
-`DELPHI_EPIDATA_KEY`. We recommend storing your key in `.Renviron` file,
-which R will read by default.
-
-Note that for the time being, the private endpoints (i.e. those prefixed
-with `pvt`) will require a separate key that needs to be passed as an
-argument.
+See the `set_api_key()` function documentation for details on how to use
+your API key.
+
+Note that the private endpoints (i.e. those prefixed with `pvt_`)
+require a separate key that needs to be passed as an argument. These
+endpoints require specific data use agreements to access.
 
 ## Get updates
 

_pkgdown.yml

@@ -36,7 +36,7 @@ reference:
   - title: Configuration and utilities
     desc: Set API keys and handle API data types
   - contents:
-      - get_auth_key
+      - get_api_key
       - avail_endpoints
       - epirange
       - timeset