Skip to contents

Run the EJAM API locally, in the background, to test/develop it

Source: R/ejamapi_local.R
ejamapi_local.Rd

Serves, on localhost, a composite of two plumber routers:

  1. At the root, a verbatim mirror of the deployed EJAM-API (inst/plumber/ejam-api/rest_controller.r – see the SYNC.md there), so local paths like /report, /data, /query, /handoff, and the Swagger docs at /__docs__/ behave like https://api.ejanalysis.com. Since the EJAM-API has no staging server, this is the way to preview how it will behave – including how it will behave after a proposed EJAM-API code edit (edit the mirror copy, rerun this, test, then submit the identical diff to the EJAM-API repo).

  2. Mounted at /draft, the draft/experimental endpoints that exist only in this package (inst/plumber/draft/plumber.R), e.g. /draft/echo, /draft/ejamit, /draft/report2, /draft/getblocksnearby.

Note local PDF report rendering requires pandoc (e.g., the RSTUDIO_PANDOC environment variable set when running outside RStudio).

Usage

ejamapi_local(
  fname = system.file("plumber/ejam-api/rest_controller.r", package = "EJAM"),
  draftfile = system.file("plumber/draft/plumber.R", package = "EJAM"),
  drafts = TRUE,
  host = "127.0.0.1",
  port = 3035,
  quiet = FALSE,
  launch_browser = interactive()
)

Arguments

fname

plumber file served at the root. Default is the mirror of the deployed EJAM-API. (Passing the older combined file, or any other plumber file, still works.)

draftfile

plumber file mounted at /draft. Default is the package's draft endpoints file.

drafts

set FALSE to serve only the EJAM-API mirror, without mounting the /draft endpoints (a pure preview of the deployed API).

host

optional, localhost IP

port

optional, a port number

quiet

optional, set to TRUE to reduce info printed to console

launch_browser

optional, set FALSE to not open /__docs__/ in a browser

Value

Invisibly, the callr::r_bg() process handle for the background server; use x$kill() to stop it, x$is_alive() to check on it, and x$read_error() to see startup errors if the server did not come up.

See also

ejamapi() and url_ejamapi()

Examples

if (FALSE) { # \dontrun{
 # launch (in a background R process) and try it from this R console
 apiproc <- EJAM:::ejamapi_local()

 # the deployed-API endpoints, served locally:
 browseURL("http://127.0.0.1:3035/report?lat=34.05&lon=-118.24&radius=3")
 df <- ejamapi(fips = "10001", endpoint = "data",
   baseurl = "http://127.0.0.1:3035/")

 # the draft-only endpoints, at /draft:
 urlx <- "http://127.0.0.1:3035/draft/getblocksnearby?lat=33&lon=-99&radius=2"
 outx <- httr2::req_perform(httr2::request(urlx))
 s2b <- data.table::rbindlist(httr2::resp_body_json(outx))

 # stop the background API process when done:
 apiproc$kill()
} # }