Learn R Programming
hakaiApi (version 1.0.5)

Client: The Hakai API Client Class

Description

Class to use to make authenticated API requests for Hakai data. Credentials can be provided via the HAKAI_API_TOKEN environment variable or through a credentials file.

Arguments

Public fields

api_root

The api_root you are logged in to

Methods

Method new()

Log into Google to gain credential access to the API

Usage

Client$new(
  api_root = "https://hecate.hakai.org/api",
  login_page = "https://hecate.hakai.org/api-client-login",
  credentials_file = NULL
)

Arguments

api_root

Optional API base url to fetch data. Defaults to "https://hecate.hakai.org/api"

login_page

Optional API login page url to display to user. Defaults to "https://hecate.hakai.org/api-client-login"

credentials_file

Optional path to the credentials cache file. Defaults to a file in the user's data directory as determined by tools::R_user_dir()

Details

Credentials can be provided in two ways: 1. Via the HAKAI_API_TOKEN environment variable (contains query string: "token_type=Bearer&access_token=...") 2. Via a credentials file (default: in user data directory via tools::R_user_dir()) The environment variable takes precedence if both are available.

Returns

A client instance

Examples

try(
   client <- Client$new()
)
# Using environment variable
Sys.setenv(HAKAI_API_TOKEN = "token_type=Bearer&access_token=TOKEN")
try(
   client <- Client$new()
)
# Using custom credentials file
try(
   client <- Client$new(credentials_file = "/path/to/creds")
)

Method get()

Send a GET request to the API

Usage

Client$get(endpoint_url, col_types = NULL)

Arguments

endpoint_url

The API endpoint url - can be a full URL or a relative path that will be appended to the api_root

col_types

a readr type specification

Returns

A dataframe of the requested data

Examples

try(client$get("/aco/views/projects"))
try(client$get("https://hecate.hakai.org/api/aco/views/projects"))

Method post()

Send a POST request to the API

Usage

Client$post(endpoint_url, rec_data)

Arguments

endpoint_url

The API endpoint url - can be a full URL or a relative path that will be appended to the api_root

rec_data

dataframe, list, or other R data structure to send as part of the post request payload

Returns

post request response status code and description

Method put()

Send a PUT request to the API

Usage

Client$put(endpoint_url, rec_data)

Arguments

endpoint_url

The API endpoint url - can be a full URL or a relative path that will be appended to the api_root

rec_data

dataframe, list, or other R data structure to send as part of the post request payload

Returns

PUT request response status code and description

Method patch()

Send a PATCH request to the API

Usage

Client$patch(endpoint_url, rec_data)

Arguments

endpoint_url

The API endpoint url - can be a full URL or a relative path that will be appended to the api_root

rec_data

dataframe, list, or other R data structure to send as part of the post request payload

Returns

PATCH request response status code and description

Method remove_credentials()

Remove your cached login credentials to logout of the client

Usage

Client$remove_credentials()

Examples

try(
   client$remove_credentials()
)

Method clone()

The objects of this class are cloneable with this method.

Usage

Client$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

Run this code
if (FALSE) {
# Initialize a new client
try(
  client <- Client$new()
)

# Or use environment variable for token
Sys.setenv(HAKAI_API_TOKEN = "token_type=Bearer&access_token=TOKEN")
try(
  client <- Client$new()
)

# Follow authorization prompts to log in

# Retrieve some data. See  for options.
try(
  projects_2020 <- client$get("/aco/views/projects?project_year=2020&fields=project_name")
)

try(
  print(projects_2020)
)
# # A tibble: 20 x 1
#    project_name
#    
#  1 Fountain FN
#  2 Haig Glacier
#  3 Fraser River - Chimney Creek West William Canyon
#  4 Cruickshank WS
#  ...
}

## ------------------------------------------------
## Method `Client$new`
## ------------------------------------------------

try(
   client <- Client$new()
)
# Using environment variable
Sys.setenv(HAKAI_API_TOKEN = "token_type=Bearer&access_token=TOKEN")
try(
   client <- Client$new()
)
# Using custom credentials file
try(
   client <- Client$new(credentials_file = "/path/to/creds")
)

## ------------------------------------------------
## Method `Client$get`
## ------------------------------------------------

try(client$get("/aco/views/projects"))
try(client$get("https://hecate.hakai.org/api/aco/views/projects"))

## ------------------------------------------------
## Method `Client$remove_credentials`
## ------------------------------------------------

try(
   client$remove_credentials()
)

Run the code above in your browser using DataLab