Skip to contents

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().

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(),
  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.

path

The route to an API endpoint. Optionally, a list with the path plus variables to glue::glue() into the path.

query

An optional list of parameters to pass in the query portion of the request.

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 use to parse the server response. 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 the response_parser function.

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.