Updated entire package to v1 of API. Package now requires an API key

.gitignore

@@ -1 +1,2 @@
-testing.R
+testing.R
+tests.R

R/api_info.R

@@ -1,7 +1,8 @@
 
 #' About ImpactStory
 #'
-#' Retrieves the latest information about the ImpactStory API
+#' Retrieves the latest information about the ImpactStory API. This package now requires an API key. You can obtain one by emailing \code{team at impactstory dot org}. Then the key can be saved in your \code{.rprofile} as \code{options(ImpactStoryKey="YOUR_KEY")} or specified inline with each function call. Any API call cannot go through without a valid key.
+#' @param key An ImpactStory API key
 #' @param as.df Default is \code{FALSE}. Set this to \code{TRUE} if you would like a \code{data.frame} returned instead.
 #' @export
 #' @return \code{list}
@@ -10,10 +11,13 @@
 #' about_IS(as.df = TRUE) # will return a nicely formatted data.frame
 #'}
 #' @author Karthik Ram \email{karthik.ram@@gmail.com}
-about_IS <- function(as.df = FALSE) {
- about <- getURL('http://api.impactstory.org')
+about_IS <- function(key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")), as.df = FALSE) {
+
+base_url <- "http://api.impactstory.org/v1"
+ url <- paste(base_url, "?key=", key, sep="")
+ about <- getURL(url)
  about <- as.list(fromJSON(I(about)))
- if(!as.df) { 
+ if(!as.df) {
  	return(about)
  	} else {
  		about_df <- ldply(about)

R/collection.R

@@ -1,36 +1,40 @@
 #' Retrives metadata on a valid ImpactStory collection ID
 #'
 #' @return a \code{list} with the following fields: \item{_id}{id #} \item{_rev}{revision #} \item{created}{created on} \item{ip_address}{ip address of creation} \item{items}{list of items} \item{key_hash}{} \item{last_modified}{} \item{owner}{} \item{title}{} \item{type}{}.
+#' @param key An ImpactStory API key
 #' @param collection_id A Impact Story collection id
 #' @param as.csv Default is \code{FALSE}. Set to \code{TRUE} to return a .csv file. Use in conjunction with \code{\link{save_collection}}
 #' @export
 #' @examples \dontrun{
 #' collection_metrics('kn5auf')
 #'}
 #' @author Karthik Ram \email{karthik.ram@@gmail.com}
-collection_metrics <- function(collection_id = NULL, as.csv = FALSE) {
+collection_metrics <- function(collection_id = NULL, key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")), as.csv = FALSE) {
 	if(is.null(collection_id))
 		stop('Did not specify a collection ID', call.=FALSE)
 
-collection_data <- getURL(paste0('http://api.impactstory.org/collection/', collection_id))		
+base_url <- "http://api.impactstory.org/v1"
+url <-  paste(base_url, "/collection/", collection_id, "?key=", key, sep="")
+
+# collection_data <- getURL(paste0('http://api.impactstory.org/v1/collection/', collection_id))
+collection_data <- getURL(url)
 
 	if(length(grep('404 Not Found', collection_data))>0 && grep('404 Not Found', collection_data)==1) {
 						stop('No metadata found for supplied collection id', call.=FALSE)
 
 		}  else {
-						if(!as.csv) {	
-				collection_data <- getURL(paste0('http://api.impactstory.org/collection/', collection_id))
+						if(!as.csv) {
 				cmd_results <- fromJSON(collection_data)
 				return(cmd_results)
 				} else {
-				 collection_data <- getURL(paste0('http://api.impactstory.org/collection/', collection_id,".csv"))	
+				 collection_data <- getURL(paste0('http://api.impactstory.org/v1/collection/',collection_id,".csv", "?key=", key))
 				 return(collection_data)
 				}
-				
+
 		}
 }
 
-#'Saves metrics from a collection to a csv file 
+#'Saves metrics from a collection to a csv file
 #'
 #' @param cid  A valid ImpactStory collection ID
 #' @param  file A filename for the \code{csv} file including path. If left blank, the file is named after the collection and stored in the current working directory.
@@ -42,15 +46,15 @@ save_collection <- function(cid = NULL, file = NULL) {
  if(is.null(cid))
  	stop("You did not specify a collection ID", call.=FALSE)
 
- # If a file name was not specified, just use the collection ID 	
+ # If a file name was not specified, just use the collection ID
  if(is.null(file)) {
- 	fname <- paste0(cid, ".csv")	
+ 	fname <- paste0(cid, ".csv")
  	} else {
- 	 fname <- paste0(file, ".csv")	
+ 	 fname <- paste0(file, ".csv")
  	}
 
 # Grab the csv data
 data <- collection_metrics(collection_id = cid, as.csv = TRUE)
 # write that to disk
  write.csv(read.csv(textConnection(data)), file = fname)
-}
+}

R/getMetrics.R

@@ -1,7 +1,8 @@
 
 #' Returns the metrics for a valid ImpactStory ID
 #'
-#' @param id  An ImpactStory ID
+#' @param key An ImpactStory API key
+#' @param id  An object ID
 #' @param nspace Namespace for the identifier. Valid namespaces include doi, github (among others). Read more about available metrics here: \url{http://impactstory.org/faq}
 #' @export
 #' @examples \dontrun{
@@ -13,15 +14,14 @@
 #' metrics('10.6084/m9.figshare.91458')
 #'}
 #' @author Karthik Ram \email{karthik.ram@@gmail.com}
-metrics <- function(id = NULL, nspace = 'doi') {
+metrics <- function(id = NULL, nspace = 'doi', key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key"))) {
 if(is.null(id))
 	stop("No id specified", call.=FALSE)
 
-id2 <- ISid(id, nspace)	
-metrics <- getURL(paste0("http://api.impactstory.org/item/", id2))
+metrics <- getURL(paste0("http://api.impactstory.org/v1/item/", nspace, "/", id, "?key=", key))
 
  if(length(grep('404 Not Found', metrics))>0 && grep('404 Not Found', metrics)==1) {
-	stop("No metrics found on supplied Impact Story ID. Supplied ID may not be valid", call.= FALSE)
+	stop("Item not found in ImpactStory database.", call.= FALSE)
 }
 
 metric_data <- fromJSON(metrics, depth = 150L)

R/tiID.R

@@ -2,7 +2,8 @@
 #' Retrieves the ImpactStory ID for a given object. (These functions will get deprecated in the next version of the API.)
 #'
 #' If an object was previously queried at ImpactStory, it will have a ImpactStory ID and this function will retrive that ID which can then be used to retrieve the latest metrics or add the item to a collection using \code{create_collection}. If the object doesn't exist in ImpactStory, this will call \code{\link{create_ISid}} and return the newly assigned ID.
-#' @param id  Any object ID 
+#' @param key An ImpactStory API key
+#' @param id  Any object ID
 #' @param  nspace Default is \code{doi} but can be changed to \code{github}, \code{url}, \code{pmid}. Others such as \code{Mendeley} and \code{arXiv} are forthcoming.
 #' @export
 #' @seealso \code{create_collection}
@@ -11,9 +12,9 @@
 #' ISid('10.1038/nrg3270')
 #'}
 #' @author Karthik Ram \email{karthik.ram@@gmail.com}
-ISid <- function(id = NULL, nspace = "doi") {
+ISid <- function(key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")), id = NULL, nspace = "doi") {
 
-ISid <- getURL(paste0('http://api.impactstory.org/tiid/', nspace, "/", id))
+ISid <- getURL(paste0('http://api.impactstory.org/v1/tiid/', nspace, "/", id))
 
  if(length(grep('404 Not Found', ISid))>0 && grep('404 Not Found', ISid)==1) {
 	  create_ISid(id, nspace)
@@ -33,7 +34,7 @@ return(str_sub(ISid, start=2, end=-2))
 #' create_ISid('10.1038/nrg3270')
 #'}
 create_ISid <- function(id = NULL, nspace = 'doi') {
-    new_id <- postForm(paste0("http://api.impactstory.org/item/", nspace, "/", id), args = NULL, style = "POST")  
+    new_id <- postForm(paste0("http://api.impactstory.org/v1/item/", nspace, "/", id), args = NULL, style = "POST")
     return(str_sub(new_id[1], start = 2, end = -2))
 }
 

R/ti_providers.R

@@ -1,6 +1,7 @@
 
 #' Returns a list of current ImpactStory data providers
 #'
+#' @param key An ImpactStory API key
 #' @param as.df = \code{FALSE}. Returns a \code{data.frame} instead of a list.
 #' @export
 #' @return \code{list}
@@ -12,8 +13,11 @@
 #'  # Note: The coercion will not be entirely clean due to the variable number of fields under description for each metric provider.
 #'}
 #' @author Karthik Ram \email{karthik.ram@@gmail.com}
-IS_providers <- function(as.df = FALSE) {
- providers <-  getURL('http://api.impactstory.org/provider')
+IS_providers <- function(key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")), as.df = FALSE) {
+
+ base_url <- "http://api.impactstory.org/v1"
+ provider_url <- paste(base_url, "/provider", "?key=", key, sep="")
+ providers <-  getURL(provider_url)
  provider_list <- (as.list(fromJSON(I(providers))))
  message("Impact Story currently provides metrics on the following data providers: ")
  message(sprintf("%s ", names(provider_list)))
@@ -28,6 +32,6 @@ IS_providers <- function(as.df = FALSE) {
    names(provider_df) <- c("Provider", "Var1", "Values1", "Var2", "Values2")
    return(provider_df)
 		}
-} 
+}
 
 

man/IS_providers.Rd

@@ -2,9 +2,12 @@
 \alias{IS_providers}
 \title{Returns a list of current ImpactStory data providers}
 \usage{
-  IS_providers(as.df = FALSE)
+  IS_providers(key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")),
+    as.df = FALSE)
 }
 \arguments{
+  \item{key}{An ImpactStory API key}
+
   \item{as.df}{= \code{FALSE}. Returns a \code{data.frame}
   instead of a list.}
 }
@@ -18,9 +21,9 @@
 \dontrun{
 IS_providers()
 IS_providers(as.df = TRUE)
-write.csv(t1_providers(as.df = TRUE), file = "total-impact-metadata.csv")
+write.csv(t1_providers(as.df = TRUE), file = "ImpactStory_metadata.csv")
  # will write the data to a flat csv file.
- # Note: The coercion will not be enISrely clean due to the variable number of fields under descripISon for each metric provider.
+ # Note: The coercion will not be entirely clean due to the variable number of fields under description for each metric provider.
 }
 }
 \author{

man/ISid.Rd

@@ -1,10 +1,13 @@
 \name{ISid}
 \alias{ISid}
-\title{Retrieves the ImpactStory ID for a given object. (These functions will get deprecated since IS is planning to remove this feature.)}
+\title{Retrieves the ImpactStory ID for a given object. (These functions will get deprecated in the next version of the API.)}
 \usage{
-  ISid(id = NULL, nspace = "doi")
+  ISid(key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")),
+    id = NULL, nspace = "doi")
 }
 \arguments{
+  \item{key}{An ImpactStory API key}
+
   \item{id}{Any object ID}
 
   \item{nspace}{Default is \code{doi} but can be changed to
@@ -17,12 +20,12 @@
 }
 \description{
   If an object was previously queried at ImpactStory, it
-  will have a IS ID and this function will retrive that ID
-  which can then be used to retrieve the latest metrics or
-  add the item to a collecISon using
+  will have a ImpactStory ID and this function will retrive
+  that ID which can then be used to retrieve the latest
+  metrics or add the item to a collection using
   \code{create_collection}. If the object doesn't exist in
-  Impact Story, this will call \code{\link{create_ISid}}
-  and return the newly assigned ID.
+  ImpactStory, this will call \code{\link{create_ISid}} and
+  return the newly assigned ID.
 }
 \examples{
 \dontrun{
@@ -33,6 +36,6 @@ ISid('10.1038/nrg3270')
   Karthik Ram \email{karthik.ram@gmail.com}
 }
 \seealso{
-  \code{create_collecISon}
+  \code{create_collection}
 }
 

man/about_IS.Rd

@@ -2,9 +2,12 @@
 \alias{about_IS}
 \title{About ImpactStory}
 \usage{
-  about_IS(as.df = FALSE)
+  about_IS(key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")),
+    as.df = FALSE)
 }
 \arguments{
+  \item{key}{An ImpactStory API key}
+
   \item{as.df}{Default is \code{FALSE}. Set this to
   \code{TRUE} if you would like a \code{data.frame}
   returned instead.}
@@ -14,7 +17,12 @@
 }
 \description{
   Retrieves the latest information about the ImpactStory
-  API
+  API. This package now requires an API key. You can obtain
+  one by emailing \code{team at impactstory dot org}. Then
+  the key can be saved in your \code{.rprofile} as
+  \code{options(ImpactStoryKey="YOUR_KEY")} or specified
+  inline with each function call. Any API call cannot go
+  through without a valid key.
 }
 \examples{
 \dontrun{

man/collection_metrics.Rd

@@ -2,9 +2,13 @@
 \alias{collection_metrics}
 \title{Retrives metadata on a valid ImpactStory collection ID}
 \usage{
-  collection_metrics(collection_id = NULL, as.csv = FALSE)
+  collection_metrics(collection_id = NULL,
+    key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")),
+    as.csv = FALSE)
 }
 \arguments{
+  \item{key}{An ImpactStory API key}
+
   \item{collection_id}{A Impact Story collection id}
 
   \item{as.csv}{Default is \code{FALSE}. Set to \code{TRUE}

man/metrics.Rd

@@ -2,10 +2,13 @@
 \alias{metrics}
 \title{Returns the metrics for a valid ImpactStory ID}
 \usage{
-  metrics(id = NULL, nspace = "doi")
+  metrics(id = NULL, nspace = "doi",
+    key = getOption("ImpactStoryKey", stop("Missing Dropbox consumer key")))
 }
 \arguments{
-  \item{id}{An ImpactStory ID}
+  \item{key}{An ImpactStory API key}
+
+  \item{id}{An object ID}
 
   \item{nspace}{Namespace for the identifier. Valid
   namespaces include doi, github (among others). Read more