ropensci · sckott · Jul 16, 2018 · Jul 16, 2018 · Jul 16, 2018 · Jul 16, 2018
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -4,9 +4,19 @@ Title: 'IUCN' Red List Client
 Description: 'IUCN' Red List (<http://apiv3.iucnredlist.org/api/v3/docs>) client.
     The 'IUCN' Red List is a global list of threatened and endangered species.
     Functions cover all of the Red List 'API' routes. An 'API' key is required.
-Version: 0.4.1.9420
-Authors@R: c(person("Scott", "Chamberlain", role = c("aut", "cre"),
-    email = "myrmecocystus@gmail.com"))
+Version: 0.4.1.9500
+Authors@R: 
+    c(person(given = "Scott",
+             family = "Chamberlain",
+             role = c("aut", "cre"),
+             email = "myrmecocystus@gmail.com"),
+      person(given = "rOpenSci",
+             role = "fnd",
+             comment = "https://ropensci.org/"),
+      person(given = "Maëlle",
+             family = "Salmon",
+             role = "ctb",
+             email = "maelle.salmon@yahoo.se"))
 License: MIT + file LICENSE
 URL: https://github.com/ropensci/rredlist
 BugReports: https://github.com/ropensci/rredlist/issues
@@ -17,4 +27,5 @@ Imports:
 Suggests:
     roxygen2 (>= 6.0.1),
     testthat
-RoxygenNote: 6.0.1
+RoxygenNote: 6.0.1.9000
+Encoding: UTF-8
diff --git a/NAMESPACE b/NAMESPACE
@@ -37,5 +37,6 @@ export(rl_synonyms)
 export(rl_synonyms_)
 export(rl_threats)
 export(rl_threats_)
+export(rl_use_iucn)
 export(rl_version)
 importFrom(jsonlite,fromJSON)
diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,8 @@
+rredlist 0.4.1.9500
+===================
+
+* Gain new function `rl_use_iucn` to help with API key setup (PR #31 by @maelle).
+
 rredlist 0.4.0
 ==============
 

diff --git a/R/rl_key.R b/R/rl_key.R
@@ -0,0 +1,21 @@
+#' Helper to get and save IUCN API key
+#'
+#' @description Browse IUCN Red List API key request URL and
+#'  provides instruction on how to store the key.
+#'
+#' @details Note that after filling the online form, you should
+#'   receive an API key shortly but not immediately.
+#'
+#' @aliases rl_use_iucn
+#'
+#' @export
+#'
+rl_use_iucn <- function(){
+  if(interactive()){
+    utils::browseURL("http://apiv3.iucnredlist.org/api/v3/token")
+  }
+
+  message("After getting your key set it as IUCN_REDLIST_KEY in .Renviron.\n IUCN_REDLIST_KEY='youractualkeynotthisstring'\n For that, use usethis::edit_r_environ()")
+
+  invisible("http://apiv3.iucnredlist.org/api/v3/token")
+}
diff --git a/R/rredlist-package.R b/R/rredlist-package.R
@@ -8,12 +8,13 @@
 #'
 #' @section Authentication:
 #' IUCN requires you to get your own API key, an alphanumeric string that you
-#' need to send in every request. Get it at
+#' need to send in every request. See key A IUCN API token. See \code{\link{rl_use_iucn}}
+#' for help getting and storing it. Get it at
 #' <http://apiv3.iucnredlist.org/api/v3/token>
 #' Keep this key private. You can pass the key in to each function via the
 #' `key` parameter, but it's better to store the key either as a
 #' environment variable (`IUCN_REDLIST_KEY`) or an R option
-#' (`iucn_redlist_key`) - we suggest using the former option.
+#' (`iucn_redlist_key`) - we recommend using the former option.
 #'
 #' @section High vs. Low level package APIs:
 #' **High level API**

diff --git a/README.Rmd b/README.Rmd
@@ -54,12 +54,13 @@ See <http://apiv3.iucnredlist.org/about>
 
 ## Authentication
 
-IUCN requires you to get your own API key, an alphanumeric string that you
-need to send in every request. Get it at <http://apiv3.iucnredlist.org/api/v3/token>.
-Keep this key private. You can pass the key in to each function via the
-`key` parameter, but it's better to store the key either as a environment
-variable (`IUCN_REDLIST_KEY`) or an R option (`iucn_redlist_key`) - we
-suggest using the former option.
+IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. There's an helper function in the package helping you getting it at <http://apiv3.iucnredlist.org/api/v3/token> and storing it.
+
+```{r}
+rredlist::rl_use_iucn()
+```
+
+Keep this key private. You can pass the key in to each function via the `key` parameter, but it's better to store the key either as a environment variable (`IUCN_REDLIST_KEY`) or an R option (`iucn_redlist_key`) - we recommend using the former option.
 
 ## High vs. Low level package APIs
 

diff --git a/man-roxygen/all.R b/man-roxygen/all.R
@@ -1,5 +1,4 @@
-#' @param key A IUCN API token. See
-#' \url{http://apiv3.iucnredlist.org/api/v3/token} to get a token
+#' @param key A IUCN API token. See \code{\link{rl_use_iucn}}.
 #' @param ... Curl options passed to \code{\link[crul]{HttpClient}}
 #' @param parse (logical) Whether to parse to list (\code{FALSE}) or
 #' data.frame (\code{TRUE}). Default: \code{TRUE}
diff --git a/man/rl_common_names.Rd b/man/rl_common_names.Rd
diff --git a/man/rl_comp_groups.Rd b/man/rl_comp_groups.Rd
diff --git a/man/rl_countries.Rd b/man/rl_countries.Rd
diff --git a/man/rl_growth_forms.Rd b/man/rl_growth_forms.Rd
diff --git a/man/rl_habitats.Rd b/man/rl_habitats.Rd
diff --git a/man/rl_history.Rd b/man/rl_history.Rd
diff --git a/man/rl_measures.Rd b/man/rl_measures.Rd
diff --git a/man/rl_narrative.Rd b/man/rl_narrative.Rd
diff --git a/man/rl_occ_country.Rd b/man/rl_occ_country.Rd
diff --git a/man/rl_regions.Rd b/man/rl_regions.Rd
diff --git a/man/rl_search.Rd b/man/rl_search.Rd
diff --git a/man/rl_sp.Rd b/man/rl_sp.Rd
diff --git a/man/rl_sp_category.Rd b/man/rl_sp_category.Rd
diff --git a/man/rl_sp_citation.Rd b/man/rl_sp_citation.Rd
diff --git a/man/rl_sp_count.Rd b/man/rl_sp_count.Rd
diff --git a/man/rl_sp_country.Rd b/man/rl_sp_country.Rd
diff --git a/man/rl_synonyms.Rd b/man/rl_synonyms.Rd
diff --git a/man/rl_threats.Rd b/man/rl_threats.Rd
diff --git a/man/rl_use_iucn.Rd b/man/rl_use_iucn.Rd
diff --git a/man/rredlist-package.Rd b/man/rredlist-package.Rd
diff --git a/tests/testthat/test-rl_key.R b/tests/testthat/test-rl_key.R
@@ -0,0 +1,6 @@
+context("test-rl_key")
+
+test_that("rl_key produces expected URL and message", {
+  expect_equal(rl_use_iucn(), "http://apiv3.iucnredlist.org/api/v3/token")
+  expect_message(rl_use_iucn(), "After getting your key set")
+})