---
title: "rCAX API query function"
description: "This vignette shows how the rCAX_GET() function works."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rCAX API query function}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(rCAX)
```

The main behind the scenes function is `rcax_GET(path, key = NULL, query=NULL, ...)` which appears in functions `rcax_table_query()` and `rcax_datasets()`.

## `rcax_GET` arguments

### path

`path` is whatever comes after `https://api.streamnet.org/api/v1` in an API call. 

For HLI tables the url is
```
https://api.streamnet.org/api/v1/ca
```
so `path="ca"`. I don't think you need `ca.json` since JSON is the default. But maybe would be good to add that to make code more robust.

### key

The API key. rCAX includes a read-only API key but if you need to use your own, see section below.

### query

This has to be a LIST of your query parameters (stuff that appears after `?` in the url for an API call). So like this:
```
list(table_id="whatevertableidis")
```

## CAX Query URL

The basic format of a query to the CAX API will look like this
```
https://api.streamnet.org/api/v1/ca.json?table_id=4EF09E86-2AA8-4C98-A983-A272C2C2C7E3&XApiKey=<your stored key>&filter=[{"field":"popid","value":"7","type":"string"}] 
```
Here we are filtering on popid equal to 7 using the filter specified with JSON. See `rcax_filter()` for a function to create the JSON from a list of colnames and values.

The `rcax_GET()` call would look like
```
qlist <- list(
  table_id=4EF09E86-2AA8-4C98-A983-A272C2C2C7E3,
  filter=rcax_filter(list(popid=7))
)
rcax_GET("ca", query=qlist)
```
This will make the API URL
```
https://api.streamnet.org/api/v1/ca
```
We don't need to pass in a key. `rcax_GET()` will look this up from the `.REnviron` file using `check_key()`. 

## Finding the table id

The `table_id` are stored in `rCAX:::caxtabs` as internal data using a call to `rcax_datasets()`. The function returns the name and id for the tables in the CAX API. `caxtabs` will need to be updated or checked periodically.

In `rcax_table_query()`, the `table_id` is looked up using a table name. The table names for the HLI short code names are hard coded in `rcax_table_name()`. If the names change, they should be updated here.

## API key

{rCAX} includes a "read-only" API key. Thus for normal read-only use, you
do not need an API key. If you need to use your own key, contact StreamNet. You can pass in your own key into calls via `GETargs$key`. 

Alternatively you can set it as as an environment variable called `CAX_KEY` in your `.Renviron` file by pasting this text into that file: `CAX_KEY='youractualkeynotthisstring'`. To do this, install the {usethis} package.
```{r eval=FALSE}
install.packages("usethis")
```
Then run this code to find or create your `.Renviron` file. It will tell you where the `.Renviron` file is.
```{r eval=FALSE}
usethis::edit_r_environ()
```
Open that file and paste in `CAX_KEY = "whateveryourkeyis"` into the file and save. After you edit the file, you will need to restart R. If you are in
RStudio use Session > Restart R. Now your API will be visible to {rCAX}. Note, if for some reason, you need to access to this key in your code, use `Sys.getenv("CAX_KEY", "")`. This retrieves variables defined in the `.Renviron` file, which are loaded into the system environment when you start up R.