R: ncurl Session

ncurl_session

R Documentation

ncurl Session

Description

nano cURL - a minimalist http(s) client. A session encapsulates a connection, along with all related parameters, and may be used to return data multiple times by repeatedly calling transact, which transacts once over the connection.

Usage

ncurl_session(
  url,
  convert = TRUE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  tls = NULL
)

transact(session)

Arguments

`url`	the URL address.
`convert`	[default TRUE] logical value whether to attempt conversion of the received raw bytes to a character vector. Set to FALSE if downloading non-text data.
`method`	(optional) the HTTP method (defaults to 'GET' if not specified).
`headers`	(optional) a named list or character vector specifying the HTTP request headers e.g. list(`Content-Type` = "text/plain") or `c(Authorization = "Bearer APIKEY")`. Supplying a non-named list or vector will error.
`data`	(optional) character request data to be submitted.
`response`	(optional) a character vector or list specifying the response headers to return e.g. `c("date", "server")` or `list("Date", "Server")`. These are case-insensitive and will return NULL if not present.
`timeout`	(optional) integer value in milliseconds after which the connection and subsequent transact attempts time out.
`tls`	(optional) applicable to secure HTTPS sites only, a client TLS Configuration object created by `tls_config`. If missing or NULL, certificates are not validated.
`session`	an 'ncurlSession' object.

Value

For ncurl_session: an 'ncurlSession' object if successful, or else an 'errorValue'.

For transact: a named list of 3 elements:

$status - integer HTTP repsonse status code (200 - OK). Use status_code for a translation of the meaning.
$headers - named list of response headers (if specified in the session), or NULL otherwise. If the status code is within the 300 range, i.e. a redirect, the response header 'Location' is automatically appended to return the redirect address.
$data - the response body as a character string (if 'convert = TRUE' was specified for the session), which may be further parsed as html, json, xml etc. as required, or else a raw byte vector, which may be saved as a file using writeBin.

Examples