Retrieve metadata for a NHS TRUD item

Sends a request to the release list endpoint, returning a list of metadata pertaining to the specified NHS TRUD item.

Usage

get_item_metadata(item, TRUD_API_KEY = NULL, latest_only = FALSE)

Arguments

item

An integer, the item to be downloaded.

TRUD_API_KEY

A string. The name of an environmental variable containing your TRUD API key. If NULL (default) this is assumed to be called TRUD_API_KEY.

latest_only

If TRUE, only metadata pertaining to the latest item release will be retrieved. By default this is set to FALSE.

Value

A list.

Examples

# \dontrun{
 # Get metadata for Community Services Data Set pre-deadline extract XML Schema
 get_item_metadata(394) |>
   purrr::map_at("releases", \(release) purrr::map(release, names))
#> $apiVersion
#> [1] "1"
#> 
#> $releases
#> $releases$CSDS_Provpredextract_1.6.6_20221115000001.zip
#>  [1] "id"                                 "name"                              
#>  [3] "releaseDate"                        "archiveFileUrl"                    
#>  [5] "archiveFileName"                    "archiveFileSizeBytes"              
#>  [7] "archiveFileSha256"                  "archiveFileLastModifiedTimestamp"  
#>  [9] "checksumFileUrl"                    "checksumFileName"                  
#> [11] "checksumFileSizeBytes"              "checksumFileLastModifiedTimestamp" 
#> [13] "signatureFileUrl"                   "signatureFileName"                 
#> [15] "signatureFileSizeBytes"             "signatureFileLastModifiedTimestamp"
#> [17] "publicKeyFileUrl"                   "publicKeyFileName"                 
#> [19] "publicKeyFileSizeBytes"             "publicKeyId"                       
#> 
#> $releases$DMDSSCHEMAS_1.5.21_20200805000001
#>  [1] "id"                                 "name"                              
#>  [3] "releaseDate"                        "archiveFileUrl"                    
#>  [5] "archiveFileName"                    "archiveFileSizeBytes"              
#>  [7] "archiveFileSha256"                  "archiveFileLastModifiedTimestamp"  
#>  [9] "checksumFileUrl"                    "checksumFileName"                  
#> [11] "checksumFileSizeBytes"              "checksumFileLastModifiedTimestamp" 
#> [13] "signatureFileUrl"                   "signatureFileName"                 
#> [15] "signatureFileSizeBytes"             "signatureFileLastModifiedTimestamp"
#> [17] "publicKeyFileUrl"                   "publicKeyFileName"                 
#> [19] "publicKeyFileSizeBytes"             "publicKeyId"                       
#> 
#> 
#> $httpStatus
#> [1] 200
#> 
#> $message
#> [1] "OK"
#> 

# Include metadata for any previous releases using `latest_only = FALSE`
get_item_metadata(394, latest_only = FALSE) |>
   purrr::map_at("releases", \(release) purrr::map(release, names))
#> $apiVersion
#> [1] "1"
#> 
#> $releases
#> $releases$CSDS_Provpredextract_1.6.6_20221115000001.zip
#>  [1] "id"                                 "name"                              
#>  [3] "releaseDate"                        "archiveFileUrl"                    
#>  [5] "archiveFileName"                    "archiveFileSizeBytes"              
#>  [7] "archiveFileSha256"                  "archiveFileLastModifiedTimestamp"  
#>  [9] "checksumFileUrl"                    "checksumFileName"                  
#> [11] "checksumFileSizeBytes"              "checksumFileLastModifiedTimestamp" 
#> [13] "signatureFileUrl"                   "signatureFileName"                 
#> [15] "signatureFileSizeBytes"             "signatureFileLastModifiedTimestamp"
#> [17] "publicKeyFileUrl"                   "publicKeyFileName"                 
#> [19] "publicKeyFileSizeBytes"             "publicKeyId"                       
#> 
#> $releases$DMDSSCHEMAS_1.5.21_20200805000001
#>  [1] "id"                                 "name"                              
#>  [3] "releaseDate"                        "archiveFileUrl"                    
#>  [5] "archiveFileName"                    "archiveFileSizeBytes"              
#>  [7] "archiveFileSha256"                  "archiveFileLastModifiedTimestamp"  
#>  [9] "checksumFileUrl"                    "checksumFileName"                  
#> [11] "checksumFileSizeBytes"              "checksumFileLastModifiedTimestamp" 
#> [13] "signatureFileUrl"                   "signatureFileName"                 
#> [15] "signatureFileSizeBytes"             "signatureFileLastModifiedTimestamp"
#> [17] "publicKeyFileUrl"                   "publicKeyFileName"                 
#> [19] "publicKeyFileSizeBytes"             "publicKeyId"                       
#> 
#> 
#> $httpStatus
#> [1] 200
#> 
#> $message
#> [1] "OK"
#> 
# }

# An informative error is raised if your API key is invalid or missing
try(download_item(394, TRUD_API_KEY = "INVALID_API_KEY"))
#> Error in download_item(394, TRUD_API_KEY = "INVALID_API_KEY") : 
#>   ✖ Can't find NHS TRUD API key
#> ℹ Set your NHS TRUD API key as an environment variable using
#>   `Sys.setenv(TRUD_API_KEY='<<your-key>>')`, or preferably use a `.Renviron`
#>   file
#> ℹ To get an API key, first sign up for a NHS TRUD account at
#>   <https://isd.digital.nhs.uk/trud/users/guest/filters/0/account/form>
#> ℹ To find Your API key, log in and visit your account profile page
#>   (<https://isd.digital.nhs.uk/trud/users/authenticated/filters/0/account/manage>).