now sending accept header version 2

also sending now user agent string with each reqeust with rdatacite versions
added some missing param defs

R/dc_client_prefixes.R

@@ -3,9 +3,9 @@
 #' @export
 #' @inheritParams dc_dois
 #' @param query (character) Query string
-#' @param year (character)
-#' @param client_id (character)
-#' @param prefix_id (character)
+#' @param year (integer/numeric/character) a year
+#' @param client_id a client ID
+#' @param prefix_id a prefix ID
 #' @param sort (character) variable to sort by
 #' @examples \dontrun{
 #' if (dc_check()) {
@@ -17,9 +17,7 @@ dc_client_prefixes <- function(query = NULL, year = NULL,
   limit = 25, page = 1, cursor = NULL, ...) {
 
   assert(query, "character")
-  assert(year, c("numeric", "integer"))
-  assert(client_id, c("numeric", "integer"))
-  assert(prefix_id, c("numeric", "integer"))
+  assert(year, c("numeric", "integer", "character"))
   assert(sort, "character")
   assert(include, "character")
   assert(limit, c("numeric", "integer"))

R/dc_clients.R

@@ -4,9 +4,9 @@
 #' @inheritParams dc_dois
 #' @param ids (character) one or more client IDs
 #' @param query (character) Query string
-#' @param year (character)
-#' @param provider_id (character)
-#' @param software (character)
+#' @param year (integer/numeric/character) a year
+#' @param provider_id a provider ID
+#' @param software no idea what should go here, anyone?
 #' @examples \dontrun{
 #' if (dc_check()) {
 #' x <- dc_clients()
@@ -21,8 +21,6 @@ dc_clients <- function(ids = NULL, query = NULL, year = NULL,
   assert(ids, "character")
   assert(query, "character")
   assert(year, c("numeric", "integer"))
-  assert(provider_id, c("numeric", "integer"))
-  assert(software, "character")
   assert(include, "character")
   assert(limit, c("numeric", "integer"))
   assert(page, c("numeric", "integer"))

R/dc_events.R

@@ -3,21 +3,28 @@
 #' @export
 #' @inheritParams dc_dois
 #' @param ids (character) one or more event IDs
-#' @param query (character) Query string
-#' @param subj_id (character) 
-#' @param obj_id (character) 
-#' @param doi (character) 
-#' @param orcid (character) 
-#' @param prefix (character) 
-#' @param subtype (character) 
-#' @param subject (character) 
-#' @param source_id (character) 
+#' @param query (character) Query for any event information
+#' @param subj_id (character) The identifier for the event subject, expressed
+#' as a URL. For example: `https://doi.org/10.7272/q6qn64nk`
+#' @param obj_id (character) The identifier for the event object, expressed
+#' as a URL. For example: `https://doi.org/10.7272/q6qn64nk`
+#' @param doi (character) The subj-id or obj-id of the event, expressed as
+#' a DOI. For example: `10.7272/q6qn64nk`
+#' @param orcid (character) an ORCID, presumably
+#' @param prefix (character) The DOI prefix of the subj-id or obj-id of the
+#' event. For example: `10.7272` 
+#' @param subtype (character) xxx
+#' @param subject (character) xxx
+#' @param source_id (character) a source ID. See Details
 #' @param registrant_id (character) 
-#' @param relation_type_id (character) 
-#' @param issn (character) 
-#' @param publication_year (character) 
-#' @param year_month (character) 
+#' @param relation_type_id (character) a relation-type ID. See Details
+#' @param issn (character) an ISSN, presumably
+#' @param publication_year (character) the publication year
+#' @param year_month (character) The year and month in which the event
+#' occurred, in the format `YYYY-MM`. For example `2018-08`
 #' @param sort (character) variable to sort by
+#' @details See https://support.datacite.org/docs/eventdata-guide for
+#' details on possible values for parameters
 #' @examples \dontrun{
 #' if (dc_check()) {
 #' x <- dc_events()
@@ -33,6 +40,25 @@ dc_events <- function(ids = NULL, query = NULL, subj_id = NULL, obj_id = NULL,
   publication_year = NULL, year_month = NULL, include = NULL,
   sort = NULL, limit = 25, page = 1, cursor = NULL, ...) {
 
+  assert(ids, "character")
+  assert(query, "character")
+  assert(subj_id, "character")
+  assert(obj_id, "character")
+  assert(doi, "character")
+  assert(orcid, "character")
+  assert(prefix, "character")
+  assert(subtype, "character")
+  assert(subject, "character")
+  assert(source_id, "character")
+  assert(registrant_id, "character")
+  assert(relation_type_id, "character")
+  assert(issn, "character")
+  assert(publication_year, c("numeric", "integer", "character"))
+  assert(year_month, "character")
+  assert(include, "character")
+  assert(limit, c("numeric", "integer"))
+  assert(page, c("numeric", "integer"))
+  assert(cursor, c("numeric", "integer", "character"))
   if (!is.null(ids)) ids <- paste0(ids, collapse = ",")
   args <- cpct(list(ids = ids, query = query, `subj-id` = subj_id,
     `obj-id` = obj_id, doi = doi, orcid = orcid, prefix = prefix,

R/dc_prefixes.R

@@ -15,6 +15,10 @@
 dc_prefixes <- function(include = NULL, limit = 25, page = 1,
   cursor = NULL, ...) {
 
+  assert(include, "character")
+  assert(limit, c("numeric", "integer"))
+  assert(page, c("numeric", "integer"))
+  assert(cursor, c("numeric", "integer", "character"))
   args <- cpct(list(include = include, `page[size]` = limit,
     `page[number]` = page, `page[cursor]` = cursor))
   as_dc(dc_GET("prefixes", args, ...), "prefixes")

R/dc_provider_prefixes.R

@@ -15,6 +15,10 @@
 dc_provider_prefixes <- function(include = NULL, limit = 25, page = 1,
   cursor = NULL, ...) {
 
+  assert(include, "character")
+  assert(limit, c("numeric", "integer"))
+  assert(page, c("numeric", "integer"))
+  assert(cursor, c("numeric", "integer", "character"))
   args <- cpct(list(include = include, `page[size]` = limit,
     `page[number]` = page, `page[cursor]` = cursor))
   as_dc(dc_GET("provider-prefixes", args, ...), "provider-prefixes")

R/dc_providers.R

@@ -2,11 +2,11 @@
 #'
 #' @export
 #' @param ids (character) one or more provider IDs
-#' @param query (character) x
-#' @param year (character) x
-#' @param region (character) x
-#' @param organization_type (character) x
-#' @param focus_area (character) x
+#' @param query (character) query string
+#' @param year (character) year
+#' @param region (character) region name
+#' @param organization_type (character) organization type
+#' @param focus_area (character) focus area
 #' @param include (character) vector of fields to return
 #' @param limit (numeric/integer) results per page
 #' @param page (numeric/integer) result page, the record to start at
@@ -23,6 +23,16 @@ dc_providers <- function(ids = NULL, query = NULL, year = NULL, region = NULL,
   organization_type = NULL, focus_area = NULL, include = NULL, limit = 25,
   page = 1, cursor = NULL, ...) {
 
+  assert(ids, "character")
+  assert(query, "character")
+  assert(year, c("numeric", "integer", "character"))
+  assert(region, "character")
+  assert(organization_type, "character")
+  assert(focus_area, "character")
+  assert(include, "character")
+  assert(limit, c("numeric", "integer"))
+  assert(page, c("numeric", "integer"))
+  assert(cursor, c("numeric", "integer", "character"))
   if (!is.null(ids)) ids <- paste0(ids, collapse = ",")
   args <- cpct(list(ids = ids, query = query, year = year, region = region,
     `organization-type` = organization_type, `focus-area` = focus_area,

R/dc_reports.R

@@ -2,12 +2,16 @@
 #'
 #' @export
 #' @param ids (character) one or more report IDs
-#' @param platform (character) x
-#' @param report_name (character) x
-#' @param report_id (character) x
-#' @param release (character) x
-#' @param created (character) x
-#' @param created_by (character) x
+#' @param platform (character) Name of the Platform the usage is being
+#' requested for. This can be omitted if the service provides usage for
+#' only one platform.
+#' @param report_name (character) The long name of the report
+#' @param report_id (character) The report ID or code or shortname. Typically
+#' this will be the same code provided in the Report parameter of the request
+#' @param release (character) The release or version of the report
+#' @param created (character) Time the report was prepared. Format as defined
+#' by date-time - RFC3339
+#' @param created_by (character) Name of the organization producing the report
 #' @param include (character) vector of fields to return
 #' @param limit (numeric/integer) results per page
 #' @param page (numeric/integer) result page, the record to start at
@@ -16,13 +20,25 @@
 #' if (dc_check()) {
 #' x <- dc_reports()
 #' x
+#' dc_reports(created = "2019-08-01T07:00:00.000Z")
+#' dc_reports(created_by = "urn:node:GOA")
 #' dc_reports(limit = 3)
 #' # dc_reports(ids = x$reports$id[1:3]) # FIXME: doesn't work
 #' }}
 dc_reports <- function(ids = NULL, platform = NULL, report_name = NULL,
   report_id = NULL, release = NULL, created = NULL, created_by= NULL,
   include = NULL, limit = 25, page = 1, ...) {
 
+  assert(ids, "character")
+  assert(platform, "character")
+  assert(report_name, "character")
+  assert(report_id, "character")
+  assert(release, "character")
+  assert(created, "character")
+  assert(created_by, "character")
+  assert(include, "character")
+  assert(limit, c("numeric", "integer"))
+  assert(page, c("numeric", "integer"))
   if (!is.null(ids)) ids <- paste0(ids, collapse = ",")
   args <- cpct(list(ids = ids, platform = platform,
     `report-name` = report_name,

R/rdatacite-package.R

@@ -1,5 +1,15 @@
 #' DataCite R client
 #'
+#' @section HTTP Requests:
+#' All HTTP requests are GET requests, and are sent with the following
+#' headers:
+#'
+#' - `Accept: application/vnd.api+json; version=2`
+#' - `User-Agent: r-curl/4.3 crul/0.9.0 rOpenSci(rdatacite/0.5.0)`
+#' - `X-USER-AGENT: r-curl/4.3 crul/0.9.0 rOpenSci(rdatacite/0.5.0)`
+#'
+#' The user-agent strings change as the versions of each package change.
+#'
 #' @section Methods in the package:
 #'
 #' - [dc_providers()]
@@ -13,9 +23,9 @@
 #' - [dc_status()]
 #' - [dc_prefixes()]
 #' - [dc_activities()]
-#' 
+#'
 #' @section rdatacite defunct functions:
-#' 
+#'
 #' - `dc_data_center`
 #' - `dc_data_centers`
 #' - `dc_facet`
@@ -33,6 +43,15 @@
 #' - `dc_work`
 #' - `dc_works`
 #'
+#' @section Content negotation:
+#' For content negotation see `rcrossref::cr_cn()`, which can be used for
+#' Crossref, DataCite and Medra DOIs
+#' 
+#' @section GraphGL API:
+#' rdatacite does not support the GraphGL API
+#' https://support.datacite.org/docs/datacite-graphql-api-guide - we suggest
+#' trying the `ghql` package (https://github.com/ropensci/ghql/)
+#'
 #' @name rdatacite-package
 #' @aliases rdatacite
 #' @docType package

R/rest_helpers.R

@@ -5,7 +5,11 @@ dc_GET <- function(route, args = NULL, discard_xml = TRUE,
   con <- crul::HttpClient$new(
   	url = dc_rest_base(),
   	opts = list(...),
-    headers = list(Accept = "application/vnd.api+json")
+    headers = list(
+      Accept = "application/vnd.api+json; version=2",
+      `User-Agent` = rdatacite_ua(),
+      `X-USER-AGENT` = rdatacite_ua()
+    )
   )
   res <- con$get(route, query = args)
   res$raise_for_status()
@@ -19,3 +23,11 @@ dc_GET <- function(route, args = NULL, discard_xml = TRUE,
 }
 
 dc_rest_base <- function() "https://api.datacite.org"
+
+rdatacite_ua <- function() {
+  versions <- c(
+    paste0("r-curl/", utils::packageVersion("curl")),
+    paste0("crul/", utils::packageVersion("crul")),
+    sprintf("rOpenSci(rdatacite/%s)", utils::packageVersion("rdatacite")))
+  paste0(versions, collapse = " ")
+}