response_process: Process a Google API response

Description

response_process() is intended primarily for internal use in client packages that provide high-level wrappers for users. Typically applied as the final step in this sequence of calls:

Request prepared with request_build().
Request made with request_make().
Response processed with response_process().

All that's needed for a successful request is to parse the JSON extracted via httr::content(). Therefore, the main point of response_process() is to handle less happy outcomes:

Status codes in the 400s (client error) and 500s (server error). The structure of the error payload varies across Google APIs and we try to create a useful message for all variants we know about.
Non-JSON content type, such as HTML.
Status code in the 100s (information) or 300s (redirection). These are unexpected.

If process_response() results in an error, a redacted version of the resp input is returned in the condition (auth tokens are removed).

Usage

response_process(resp, error_message = gargle_error_message, remember = TRUE)
response_as_json(resp)
gargle_error_message(resp)

Value

The content of the request, as a list. An HTTP status code of 204 (No content) is a special case returning TRUE.

Arguments

resp: Object of class response from httr.
error_message: Function that produces an informative error message from the primary input, resp. It must return a character vector.
remember: Whether to remember the most recently processed response.

Details

When remember = TRUE (the default), gargle stores the most recently seen response internally, for post hoc examination. The stored response is literally just the most recent resp input, but with auth tokens redacted. It can be accessed via the unexported function gargle:::gargle_last_response(). A companion function gargle:::gargle_last_content() returns the content of the last response, which is probably the most useful form for post mortem analysis.

The response_as_json() helper is exported only as an aid to maintainers who wish to use their own error_message function, instead of gargle's built-in gargle_error_message(). When implementing a custom error_message function, call response_as_json() immediately on the input in order to inherit gargle's handling of non-JSON input.

Examples

Run this code

if (FALSE) {
# get an OAuth2 token with 'userinfo.email' scope
token <- token_fetch(scopes = "https://www.googleapis.com/auth/userinfo.email")

# see the email associated with this token
req <- gargle::request_build(
  method = "GET",
  path = "v1/userinfo",
  token = token,
  base_url = "https://openidconnect.googleapis.com"
)
resp <- gargle::request_make(req)
response_process(resp)

# make a bad request (this token has incorrect scope)
req <- gargle::request_build(
  method = "GET",
  path = "fitness/v1/users/{userId}/dataSources",
  token = token,
  params = list(userId = 12345)
)
resp <- gargle::request_make(req)
response_process(resp)
}