request_develop: Build a Google API request

View source: R/request_develop.R

request_developR Documentation

Build a Google API request


Intended primarily for internal use in client packages that provide high-level wrappers for users. The vignette("request-helper-functions") describes how one might use these functions inside a wrapper package.


  params = list(),
  base_url = ""

  method = "GET",
  path = "",
  params = list(),
  body = list(),
  token = NULL,
  key = NULL,
  base_url = ""



List of information about the target endpoint or, in Google's vocabulary, the target "method". Presumably prepared from the Discovery Document for the target API.


Named list. Values destined for URL substitution, the query, or, for request_develop() only, the body. For request_build(), body parameters must be passed via the body argument.




Character. An HTTP verb, such as GET or POST.


Character. Path to the resource, not including the API's base_url. Examples: drive/v3/about or drive/v3/files/{fileId}. The path can be a template, i.e. it can include variables inside curly brackets, such as {fileId} in the example. Such variables are substituted by request_build(), using named parameters found in params.


List. Values to send in the API request body.


Token, ready for inclusion in a request, i.e. prepared with httr::config().


API key. Needed for requests that don't contain a token. For more, see Google's document Credentials, access, security, and identity (⁠⁠). A key can be passed as a named component of params, but note that the formal argument key will clobber it, if non-NULL.


request_develop(): list() with components method, path, params, body, and base_url.

request_build(): list() with components method, path (post-substitution), query (the input params not used in URL substitution), body, token, url (the full URL, post-substitution, including the query).


Combines user input (params) with information about an API endpoint. endpoint should contain these components:

  • path: See documentation for argument.

  • method: See documentation for argument.

  • parameters: Compared with params supplied by user. An error is thrown if user-supplied params aren't named in endpoint$parameters or if user fails to supply all required parameters. In the return value, body parameters are separated from those destined for path substitution or the query.

The return value is typically used as input to request_build().


Builds a request, in a purely mechanical sense. This function does nothing specific to any particular Google API or endpoint.

  • Use with the output of request_develop() or with hand-crafted input.

  • params are used for variable substitution in path. Leftover params that are not bound by the path template automatically become HTTP query parameters.

  • Adds an API key to the query iff token = NULL and removes the API key otherwise. Client packages should generally pass their own API key in, but note that gargle_api_key() is available for small-scale experimentation.

See googledrive::generate_request() for an example of usage in a client package. googledrive has an internal list of selected endpoints, derived from the Drive API Discovery Document (⁠⁠), exposed via googledrive::drive_endpoints(). An element from such a list is the expected input for endpoint. googledrive::generate_request() is a wrapper around request_develop() and request_build() that inserts a googledrive-managed API key and some logic about Team Drives. All user-facing functions use googledrive::generate_request() under the hood.

See Also

Other requests and responses: request_make(), response_process()


## Not run: 
## Example with a prepared endpoint
ept <- googledrive::drive_endpoints("drive.files.update")[[1]]
req <- request_develop(
  params = list(
    fileId = "abc",
    addParents = "123",
    description = "Exciting File"

req <- request_build(
  method = req$method,
  path = req$path,
  params = req$params,
  body = req$body,
  token = "PRETEND_I_AM_A_TOKEN"

## Example with no previous knowledge of the endpoint
## List a file's comments
req <- request_build(
  method = "GET",
  path = "drive/v3/files/{fileId}/comments",
  params = list(
    fileId = "your-file-id-goes-here",
    fields = "*"
  token = "PRETEND_I_AM_A_TOKEN"

# Example with no previous knowledge of the endpoint and no token
# use an API key for which the Places API is enabled!
API_KEY <- "1234567890"

# get restaurants close to a location in Vancouver, BC
req <- request_build(
  method = "GET",
  path = "maps/api/place/nearbysearch/json",
  params = list(
    location = "49.268682,-123.167117",
    radius = 100,
    type = "restaurant"
  key = API_KEY,
  base_url = ""
resp <- request_make(req)
out <- response_process(resp)
vapply(out$results, function(x) x$name, character(1))

## End(Not run)

ropenscilabs/gauth documentation built on Sept. 11, 2023, 6:20 a.m.