| Title: | This is a wrapper for the Harvest REST API v2. |
|---|---|
| Description: | The foremost function of this package is to act as a *convenient* wrapper around the Harvest REST API v2. To that end, the package handles credentials either through the system keyring using the `keyring` package (preferred), or through environment variables written to a local `.Renviron` file. Credential handling can be initiated explicitly, but otherwise happens automatically upon making an API request. This package tries to make accessing the Harvest API as easy as possible. While it does allow some tweaking of the actual HTTP request via function arguments, the primary method for accessing API data is to simply select which resource to query (e.g. "users" will download all users data). *Note, that the default is to only download "active" records.* The reason for this mode of access is that a request usually isn't very big and the typical user will probably want to manipulate the data in a more sophisticated manner for some downstream visualization or other analysis. Building on this premise, the secondary function of this package is to manage the long term storage of API data to minimize remote requests. This is achieved by storing API data in a local SQLite database, for which this package also provides a straightforward way of accessing and updating with new data. There is a companion Shiny application (hRvst) which utilizes this wrapper for Harvest API data access, and perhaps slightly enhances this package. |
| Authors: | Eric Hunt [aut, cre] |
| Maintainer: | Eric Hunt <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.0.9000 |
| Built: | 2025-03-08 04:16:20 UTC |
| Source: | https://github.com/eric-hunt/hRvstAPI |
This is intended to be a helper function for setting credentials.
add_creds(.report = NULL)add_creds(.report = NULL)
.report |
A list – report returned from hRvstAPI::check_creds() |
Useful for informing subsequent user action within an application.
check_creds()check_creds()
A list – variables related to credential existence.
This is intended to be a helper function for setting credentials.
clear_environment_creds()clear_environment_creds()
This is intended to be a helper function for setting credentials.
clear_keyring_creds()clear_keyring_creds()
Create a SQLite database to hold Harvest API v2 request data.
create_db(db_path = NULL, rds_path = NULL)create_db(db_path = NULL, rds_path = NULL)
db_path |
A string – file path where a local .sqlite file containing Harvest API data should be created. |
rds_path |
A string – file path where a local .rds file containing Harvest API data should exist. |
Download Harvest API v2 requests into a local file.
create_rds( ..., is_active = NULL, updated_since = NULL, weeks_ago = NULL, from = NULL, to = NULL, rds_path = NULL, sql_colnames = TRUE, .extra_params = NULL )create_rds( ..., is_active = NULL, updated_since = NULL, weeks_ago = NULL, from = NULL, to = NULL, rds_path = NULL, sql_colnames = TRUE, .extra_params = NULL )
... |
Resources as "named" key/value pairs to be requested. ( |
is_active |
A string – 'true' or 'false' passed to |
updated_since |
A string – passed to |
weeks_ago |
An integer – overrides updated_since argument; the number of weeks prior to the current week to convert to a date and pass to the 'updated_since' query parameter. |
from |
TODO |
to |
TODO |
rds_path |
A string – file path where a local .rds file containing Harvest API data should be created. |
sql_colnames |
A Boolean – automatically convert '.' to '_' in column names for easier SQL query construction. |
.extra_params |
Key-value pairs – optional additional query parameters passed to |
Get the unique set of key values that already exist in a table.
get_keys(db_connection, tbl, key = NULL)get_keys(db_connection, tbl, key = NULL)
db_connection |
A DBI compatible connection object – the database containing Harvest API v2 request data. |
tbl |
A string – name of the table from which to gather primary keys. |
key |
A string – name of the primary key column in tbl. |
A numeric vector – a vector of integer primary keys which currently exist in tbl.
Return the user's Harvest API v2 account ID.
hrvst_acct_id()hrvst_acct_id()
A string – the user account ID.
Harvest API V2 Documentation | Authentication
The basic headers that are automatically set in this function are
Harvest-Account-Id, Authorization, and User-Agent. Other headers
can be added by the user and will be concatenated, but currently
these important headers are set by the hRvstAPI::hrvst_acct_id(),
hRvstAPI::hrvst_token(), and hRvstAPI::.agent objects.
hrvst_GET( url = NULL, headers = NULL, is_active = NULL, updated_since = NULL, from = NULL, to = NULL, ... )hrvst_GET( url = NULL, headers = NULL, is_active = NULL, updated_since = NULL, from = NULL, to = NULL, ... )
url |
A string – the URL component for Harvest API v2 requests (NULL will default to .url). |
headers |
A list – the headers required for authentication of each Harvest API v2 request: 'Harvest-Account-Id', 'Authorization' (PAT), and 'User-Agent' (this package GitHub repo, .agent). |
is_active |
A string – 'true' or 'false' (Boolean per Harvest API requirement) should only active ('true') or inactive ('false') records be requested; default NULL downloads all records. |
updated_since |
A string – a date or date/time value (in ISO8601 character format) indicated how far back in time to retrieve records. Not supported by all of the Harvest v2 APIs. |
from |
TODO |
to |
TODO |
... |
Key-value pairs – optional additional query parameters. |
An HTTP response: an S3 list with class httr2_request.
This is the primary function used to gather resources from the
Harvest API v2. It uses hrvst_GET() to construct
an httr2::request() and then performs that request after
modifying the URL.
Requests are automatically throttled to comply with Harvest API v2 constraints.
hrvst_req( resource = NULL, all_pages = TRUE, base_url = NULL, headers = NULL, is_active = "true", updated_since = NULL, weeks_ago = NULL, from = NULL, to = NULL, ... )hrvst_req( resource = NULL, all_pages = TRUE, base_url = NULL, headers = NULL, is_active = "true", updated_since = NULL, weeks_ago = NULL, from = NULL, to = NULL, ... )
resource |
A string – modifies the URL path to point to a specific Harvest API v2 resource. Currently available options:
|
all_pages |
A Boolean – should all pages be gathered for a requested resource? (default value TRUE) |
base_url |
– A string – the common URL component for Harvest API v2 requests, passed to |
headers |
A list – passed to |
is_active |
A string – 'true' or 'false' passed to |
updated_since |
A string – passed to |
weeks_ago |
An integer – overrides updated_since argument; the number of weeks prior to the current week to convert to a date and pass to the 'updated_since' query parameter. |
from |
TODO |
to |
TODO |
... |
Key-value pairs – passed to |
If only a specific page is required, the page = [n] parameter
can be passed to ... to be added to the query parameters.
Adding this query parameter will automatically set all_pages
to FALSE.
A tibble::tibble() of all response content.
Harvest API V2 Documentation | Rate Limiting
Return the user's Harvest API v2 personal access token.
hrvst_token()hrvst_token()
A string – the user personal access token.
Harvest API V2 Documentation | Authentication
Get the name of the primary key column for a table.
key_col(db_connection, tbl)key_col(db_connection, tbl)
db_connection |
A DBI compatible connection object – the database containing Harvest API v2 request data. |
tbl |
A string – name of the table for which to determine the primary key column. |
A string – the primary key column of tbl.
These are common values used by hRvstAPI functions like the base URL for the Harvest API v2, and the name of the hRvstAPI GitHub repo for a user agent to be logged with each GET request made to the Harvest API. In the future these may be set as options to give the user even more control over this wrapper.
.service .url .agent .rds_path .db_path.service .url .agent .rds_path .db_path
An object of class character of length 1.
An object of class character of length 1.
An object of class character of length 1.
An object of class fs_path (inherits from character) of length 1.
An object of class fs_path (inherits from character) of length 1.
Query the local database and collect/return the result.
query_db(query_string, ..., .is_active = TRUE, .db_loc = hRvstAPI::.db_path)query_db(query_string, ..., .is_active = TRUE, .db_loc = hRvstAPI::.db_path)
query_string |
A string – the query to be executed. |
... |
Key-value pairs – additional arguments for interpolation passed to |
.is_active |
A Boolean – restrict results to active entries; defaults to TRUE |
.db_loc |
A string – file path where a local .sqlite file containing Harvest API data should exist. |
A tibble::tibble() of data collected from the query.
This is intended to be a helper function for setting credentials.
retrieve_creds(.report = NULL)retrieve_creds(.report = NULL)
.report |
A list – report returned from hRvstAPI::check_creds() |
Set user credentials as environment variables.
set_creds()set_creds()
Update the local SQLite database with new Harvest API v2 request data.
update_db(db_path = NULL, rds_path = NULL)update_db(db_path = NULL, rds_path = NULL)
db_path |
A string – file path where a local .sqlite file containing Harvest API data should be updated. |
rds_path |
A string – file path where a local .rds file containing Harvest API data should exist. |