---
title: "RAQSAPI - Using RAQSAPI"
author: "Clinton Mccrowey physical scientist - US EPA"
date: "April 5, 2021"
output:
  rmarkdown::html_vignette: default
vignette: >
  %\VignetteIndexEntry{RAQSAPI - Using RAQSAPI}
  %\VignetteEncoding{UTF-8}
  %\VignetteDepends{knitr}
  %\VignetteDepends{rmarkdown}
  %\VignetteEngine{knitr::rmarkdown}
---

# Using The RAQSAPI library

## Load RAQSAPI                           
  after successfully installing the `RAQSAPI` package, load the `RAQSAPI`
  library: 

```R
library(RAQSAPI)
```

## Sign up and setting up user credentials with the RAQSAPI library

If you have not already done so you will need to sign up with AQS Data Mart
  using aqs_sign_up function, ^[Use "?aqs_sign_up" after the RAQSAPI library has
  been loaded to see the full usage description of the aqs_sign_up
  function.] this function takes one input, "email", which is a R
  character object, that represents the email address that you want to use
  as a user credential to the AQS Data Mart service. After a successful call to
  aqs_sign_up an email message will be sent to the email address provided
  with a new Data Mart key which will be used as a credential key to access the
  Data Mart API. The aqs_sign_up function can also be used to regenerate a
  new key for an existing user, to generate a new key simply call the
  aqs_sign_up function with the parameter "email" set to an existing
  account. A new key will be e-mailed to the account given.

The credentials used to access the Data Mart API service are stored in a R
  environment variable that needs to be set every time the `RAQSAPI` library is
  attached or the key is changed. Without valid credentials, the Data Mart
  server will reject any request sent to it. The key used with Data Mart is a
  key and is not a password, so the RAQSAPI library does not treat the key as a
  password; this means that the key is stored in plain text and there are no
  attempts to encrypt Data Mart credentials as would be done for a username and
  password combination. The key that is supplied to use with Data Mart is not
  intended for authentication but only account monitoring. Each time RAQSAPI is
  loaded and before using any of it's functions use the aqs_credentials ^[Use
  "?aqs_credentials" after the RAQSAPI library has been loaded to see the full
  usage description of the aqs_credentials function.] function
  to enter in the user credentials so that RAQSAPI can access the AQS Data Mart
  server.

| <span style="color:red"> Note: The credentials used to access AQS Data Mart \
API is not the same as the credentials used to access AQS. AQS users who do \
not have access to the AQS Data Mart will need to create new credentials. \
</span> |
| -- |


## (suggested) Use the `keyring` package to manage credentials
It is highly suggested that users use a keyring manager to store and retrieve
their credentials while using RAQSAPI. One such credential manager is provided
by the `keyring`
package ^[[R `Keyring` package]https://cran.r-project.org/package=keyring)].
The `Keyring` package uses the credential manager available for most popular
operating systems to store and manage user credentials. This will help avoid
hard coding credential information into R scripts.

To use the `keyring` package with `RAQSAPI` first install `keyring`:

```R
install.package("keyring")
```

Ensure that your system is supported by the `keyring` package before proceeding.

```R
  keyring::has_keyring_support()
```

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

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

a popup window will appear for the user to input their keyring information.
Enter the AQS Data mart credential key associated with the AQS user name
provided, then hit enter. Now the AQS Data Mart user credential is set using
`keyring`.

To retrieve the keyring to use with `RAQSAPI` load the `keyring` package and use
the function key_get to return the user credential to RAQSAPI:

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

then pass these variables to the aqs_credentials function when using RAQSAPI:

```R
  aqs_credentials(username = datamartAPI_user,
                  key = key_get(service = server,
                                username = datamartAPI_user
                                )
                  )
```
To change the keyring stored with the `keyring` package repeat the steps above
to call the keyring::key_set function again with the new credential information.

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

Refer the the[`keyring` package documentation](
https://cran.r-project.org/package=keyring/readme/README.html)
for an in depth explanation on using the `keyring` package.