Send a request to an API

This function implements an opinionated framework for making API calls. It is intended to be used inside an API client package. It serves as a wrapper around the req_ family of functions, such as httr2::request(), as well as httr2::req_perform() and httr2::req_perform_iterative(), and, by default, httr2::resp_body_json().

Usage

call_api(
  base_url,
  ...,
  path = NULL,
  query = NULL,
  body = NULL,
  mime_type = NULL,
  method = NULL,
  security_fn = NULL,
  security_args = list(),
  response_parser = httr2::resp_body_json,
  response_parser_args = list(),
  next_req = NULL,
  max_reqs = Inf,
  max_tries_per_req = 3,
  user_agent = "nectar (https://nectar.api2r.org)"
)

Arguments

base_url: The part of the url that is shared by all calls to the API. In some cases there may be a family of base URLs, from which you will need to choose one.
...: These dots are for future extensions and must be empty.
path: The route to an API endpoint. Optionally, a list or character vector with the path as one or more unnamed arguments (which will be concatenated with "/") plus named arguments to glue::glue() into the path.
query: An optional list or character vector of parameters to pass in the query portion of the request. Can also include a .multi argument to pass to httr2::req_url_query() to control how elements containing multiple values are handled.
body: An object to use as the body of the request. If any component of the body is a path, pass it through fs::path() or otherwise give it the class "fs_path" to indicate that it is a path.
mime_type: A character scalar indicating the mime type of any files present in the body. Some APIs allow you to leave this as NULL for them to guess.
method: If the method is something other than GET or POST, supply it. Case is ignored.
security_fn: A function to use to authenticate the request. By default (NULL), no authentication is performed.
security_args: An optional list of arguments to the security_fn function.
response_parser: A function to parse the server response (resp). Defaults to httr2::resp_body_json(), since JSON responses are common. Set this to NULL to return the raw response from httr2::req_perform().
response_parser_args: An optional list of arguments to pass to the response_parser function (in addition to resp).
next_req: An optional function that takes the previous response (resp) to generate the next request in a call to httr2::req_perform_iterative(). This function can usually be generated using one of the iteration helpers described in httr2::iterate_with_offset().
max_reqs: The maximum number of separate requests to perform. Passed to the max_reqs argument of httr2::req_perform_iterative() when next_req is supplied. The default 2 should likely be changed to Inf after you validate the function.
max_tries_per_req: The maximum number of times to attempt each individual request. Passed to the max_tries argument of httr2::req_retry().
user_agent: A string to identify where this request is coming from. It's polite to set the user agent to identify your package, such as "MyPackage (https://mypackage.com)".

Value

The response from the API, parsed by the response_parser.

Usage

Arguments

Value

See also