Load RAQSAPI

after successfully installing theRAQSAPI package, loadtheRAQSAPI library:

library(RAQSAPI)

Sign up and setting up user credentials with the RAQSAPIlibrary

If you have not already done so you will need to sign up with AQSData Mart using aqs_sign_up function,¹ this function takesone input, “email”, which is a R character object, that represents theemail address that you want to use as a user credential to the AQS DataMart service. After a successful call to aqs_sign_up an email messagewill be sent to the email address provided with a new Data Mart keywhich will be used as a credential key to access the Data Mart API. Theaqs_sign_up function can also be used to regenerate a new key for anexisting user, to generate a new key simply call the aqs_sign_upfunction with the parameter “email” set to an existing account. A newkey will be e-mailed to the account given.

The credentials used to access the Data Mart API service are storedin a R environment variable that needs to be set every time theRAQSAPI library is attached or the key is changed. Withoutvalid credentials, the Data Mart server will reject any request sent toit. The key used with Data Mart is a key and is not a password, so theRAQSAPI library does not treat the key as a password; this means thatthe key is stored in plain text and there are no attempts to encryptData Mart credentials as would be done for a username and passwordcombination. The key that is supplied to use with Data Mart is notintended for authentication but only account monitoring. Each timeRAQSAPI is loaded and before using any of it’s functions use theaqs_credentials² function to enter in the user credentialsso that RAQSAPI can access the AQS Data Mart server.

(suggested) Use thekeyring package to managecredentials

It is highly suggested that users use a keyring manager to store andretrieve their credentials while using RAQSAPI. One such credentialmanager is provided by thekeyring package³. TheKeyring package uses the credential manager available formost popular operating systems to store and manage user credentials.This will help avoid hard coding credential information into Rscripts.

To use thekeyring package withRAQSAPIfirst installkeyring:

install.package("keyring")

Ensure that your system is supported by thekeyringpackage before proceeding.

  keyring::has_keyring_support()

then set the keyring used to access AQS Data Mart (make sure toreplace the text in the angled brackets with your specific userinformation):

library("keyring")  keyring::key_set(service ="AQSDatamart",username ="\<user email account\>")

a popup window will appear for the user to input their keyringinformation. Enter the AQS Data mart credential key associated with theAQS user name provided, then hit enter. Now the AQS Data Mart usercredential is set usingkeyring.

To retrieve the keyring to use withRAQSAPI load thekeyring package and use the function key_get to return theuser credential to RAQSAPI:

library(RAQSAPI)library(keyring)  datamartAPI_user<- \<user email account\>  server<-"AQSDatamart"

then pass these variables to the aqs_credentials function when usingRAQSAPI:

aqs_credentials(username = datamartAPI_user,key =key_get(service = server,username = datamartAPI_user                                )                  )

To change the keyring stored with thekeyring packagerepeat the steps above to call the keyring::key_set function again withthe new credential information.

To retrieve a list of all keyrings managed with thekeyring package use the function: >keyring::key_list()

Refer the thekeyringpackage documentation for an in depth explanation on using thekeyring package.