Package {apifetch}

apifetch: Token-Authenticated REST API Retrieval Toolkit

Description

A small, dependency-light toolkit for talking to token-authenticated REST APIs. It manages authentication tokens in process environment variables (never written to disk), builds requests with configurable authentication and pagination strategies, and retrieves paginated data either one page at a time or in chunks combined into a single tibble. The design is API-agnostic: a single 'apifetch_api' profile describes an endpoint together with how it authenticates and paginates, so the same verbs work across different services.

Author(s)

Maintainer: André Leite leite@castlab.org

Authors:

• André Leite leite@castlab.org

• Hugo Vasconcelos hugo.vasconcelos@ufpe.br

• Diogo Bezerra diogo.bezerra@ufpe.br

• Marcos Wasilew marcos.wasilew@gmail.com

• Carlos Amorin carlos.agaf@ufpe.br

See Also

Useful links:

• https://github.com/StrategicProjects/apifetch

• https://strategicprojects.github.io/apifetch/

• Report bugs at https://github.com/StrategicProjects/apifetch/issues

Describe an API endpoint

Description

Bundles an endpoint URL with its authentication and pagination strategies and a namespace service (used to look up tokens). The resulting object is passed to af_fetch() and af_fetch_all().

Usage

af_api(
  endpoint,
  service = "apifetch",
  auth = af_auth_bearer(),
  pagination = af_paginate_offset(),
  drop_cols = character(0),
  connect_hint = NULL
)

Arguments

Value

An apifetch_api object.

Examples

af_api(
  endpoint = "https://www.bigdata.pe.gov.br/api/buscar",
  service = "BigDataPE",
  auth = af_auth_raw(),
  pagination = af_paginate_offset("header"),
  drop_cols = "Mensagem",
  connect_hint = "Ensure you are on the PE Conectado network or VPN."
)

Authentication strategies

Description

Constructors describing how a token is attached to a request. Pass the result to the auth argument of af_api().

Usage

af_auth_raw(header = "Authorization")

af_auth_bearer(header = "Authorization", prefix = "Bearer ")

af_auth_header(header = "X-API-Key")

af_auth_query(param = "api_key")

Arguments

Details

• af_auth_raw(): send the token verbatim in a header (default Authorization). This is what the Big Data PE API expects.

• af_auth_bearer(): send "Bearer <token>" in the Authorization header.

• af_auth_header(): send the token in an arbitrary header (e.g. X-API-Key).

• af_auth_query(): send the token as a URL query parameter.

Value

An apifetch_auth object.

Examples

af_auth_raw()
af_auth_bearer()
af_auth_header("X-API-Key")
af_auth_query("api_key")

Fetch a single page from an API

Description

Performs one authenticated request against an af_api() profile, applying its pagination strategy, and returns the parsed body as a tibble. HTTP errors and connection failures are translated into friendly cli messages.

Usage

af_fetch(api, name, limit = Inf, offset = 0L, query = list(), verbosity = 0L)

Arguments

Value

A tibble with the parsed response.

Examples

## Not run: 
api <- af_api("https://www.bigdata.pe.gov.br/api/buscar",
              service = "BigDataPE", auth = af_auth_raw(),
              pagination = af_paginate_offset("header"))
af_store_token("dengue", "token", service = "BigDataPE")
af_fetch(api, "dengue", limit = 50)

## End(Not run)

Fetch all data from an API in chunks

Description

Iteratively calls af_fetch() with an advancing offset, stopping when a chunk comes back empty or total_limit is reached, then row-binds the chunks into one tibble. Columns listed in the API profile's drop_cols are removed.

Usage

af_fetch_all(
  api,
  name,
  total_limit = Inf,
  chunk_size = 50000L,
  query = list(),
  verbosity = 0L
)

Arguments

Value

A tibble with all retrieved records.

Examples

## Not run: 
api <- af_api("https://www.bigdata.pe.gov.br/api/buscar",
              service = "BigDataPE", auth = af_auth_raw(),
              pagination = af_paginate_offset("header"),
              drop_cols = "Mensagem")
af_fetch_all(api, "dengue", total_limit = 500, chunk_size = 100)

## End(Not run)

Retrieve a stored API token

Description

Retrieves the token stored for name under service. Returns NULL (with a warning) rather than erroring when no token is found.

Usage

af_get_token(name, service = "apifetch")

Arguments

Value

The token string, or NULL if not found.

Examples

token <- af_get_token("dengue", service = "BigDataPE")

List stored API tokens

Description

Returns the names (without the service prefix) of all tokens stored for a given service in environment variables.

Usage

af_list_tokens(service = "apifetch")

Arguments

Value

A character vector of token names, empty if none are found.

Examples

af_list_tokens(service = "BigDataPE")

Pagination strategies

Description

Constructors describing how limit/offset are sent with a request. Pass the result to the pagination argument of af_api().

Usage

af_paginate_offset(
  where = c("header", "query"),
  limit_param = "limit",
  offset_param = "offset"
)

af_paginate_none()

Arguments

Details

• af_paginate_offset(): send limit/offset either as HTTP headers (default, as the Big Data PE API expects) or as URL query parameters.

• af_paginate_none(): send no pagination parameters.

Non-positive or infinite values are omitted from the request.

Value

An apifetch_pagination object.

Examples

af_paginate_offset("header")
af_paginate_offset("query", limit_param = "per_page")
af_paginate_none()

Remove a stored API token

Description

Removes the token stored for name under service. Does nothing (beyond a warning) when no token is found.

Usage

af_remove_token(name, service = "apifetch")

Arguments

Value

Invisibly NULL; called for its side effect.

Examples

af_remove_token("dengue", service = "BigDataPE")

Store an API token in an environment variable

Description

Stores an authentication token in a process environment variable named "<service>_<name>". The token is never written to disk. If a non-empty variable with that name already exists, the function refuses to overwrite it.

Usage

af_store_token(name, token, service = "apifetch")

Arguments

Value

Invisibly NULL; called for its side effect.

Examples

bdpe <- af_store_token("dengue", "your-token-here", service = "BigDataPE")

Build a URL with query parameters

Description

Appends a named list of query parameters to a base URL, URL-encoding both names and values and dropping parameters whose value is the empty string.

Usage

parse_queries(url, query_list)

Arguments

Value

The URL with the query string appended (or the base URL unchanged when there are no parameters to add).

Examples

parse_queries("https://example.com", list(a = "1", b = "2"))