Add an API endpoint to authentication state

Registers where an API lives. Call this from your package's .onLoad().

Usage

add_api(name, url, realm = NULL)

Arguments

name

String. Name of the API to add

url

Character. One address per region, named by region or all — see Addresses. A single unnamed URL is accepted as the older form.

realm

String. Optional realm name to join. If NULL (default), a new realm is created with the API name. If provided, the API joins an existing realm and shares its token.

Value

Invisibly returns TRUE if API was added or already exists with same URL, FALSE if API exists with different URL

Addresses

Give one address per region, named by region, or a single address named all for a service deployed once and reached from everywhere:

c(us = ..., ca = ...)	mirrored per region
c(all = ...)	one deployment every region shares

The region picks between them when the URL is read, not when the API is registered — registration happens at load, so a region set afterwards would otherwise be too late.

A single unnamed URL is the older form, from before addresses were declared. It still resolves in the "us" region, with one warning per package per session, and is an error anywhere else: the address for that region is genuinely unknown, and quietly using another region's host would send the request out of the country and succeed.

See also

api_url() to see the URL an API resolves to, APIAuthState for the underlying state object

Examples

if (FALSE) { # \dontrun{
# In package's .onLoad — creates the "counts" realm
add_api("counts", c(
  us = "https://counts.spdgt.com/api",
  ca = "https://counts.ca.spdgt.com/api"
))

# Satellite API joins the counts realm
add_api("sightability", c(
  us = "https://sightability.spdgt.com/api",
  ca = "https://sightability.ca.spdgt.com/api"
), realm = "counts")

# One deployment every region shares
add_api("support", c(all = "https://support.spdgt.com/api"),
  realm = "counts")
} # }