hakaiApi: Authenticated HTTP Request Client for the 'Hakai' API

Description

Initializes a class that obtains API credentials and provides a method to use those credentials to make GET requests to the 'Hakai' API server. Usage instructions are documented at https://hakaiinstitute.github.io/hakai-api/.

Author(s)

Maintainer: Sam Albers sam.albers@hakai.org

Authors:

• Taylor Denouden taylor.denouden@hakai.org

• Brett Johnson brett.johnson@hakai.org

Other contributors:

• Nate Rosenstock nate.rosenstock@hakai.org [contributor]

• Chris Davis chris.davis@hakai.org [contributor]

• Hakai Institute [copyright holder]

See Also

Useful links:

• https://github.com/HakaiInstitute/hakai-api-client-r

• Report bugs at https://github.com/HakaiInstitute/hakai-api-client-r/issues

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.

Public fields

Methods

Public methods

• Client$new()

• Client$get()

• Client$post()

• Client$put()

• Client$patch()

• Client$remove_credentials()

• Client$clone()

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

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

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

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

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

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

Examples

## Not run: 
# 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 <https://hakaiinstitute.github.io/hakai-api/> 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
#    <chr>
#  1 Fountain FN
#  2 Haig Glacier
#  3 Fraser River - Chimney Creek West William Canyon
#  4 Cruickshank WS
#  ...

## End(Not run)

## ------------------------------------------------
## 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()
)