ncurl_session: 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)

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 (all headers if response = TRUE was specified for the session, those specified in response, or NULL otherwise).
$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().

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 as a character string. Defaults to 'GET' if not specified, and could also be 'POST', 'PUT' etc.
headers: (optional) a named character vector specifying the HTTP request headers, for example:
c(Authorization = "Bearer APIKEY", "Content-Type" = "text/plain")
A non-character or non-named vector will be ignored.
data: (optional) request data to be submitted. Must be a character string or raw vector, and other objects are ignored. If a character vector, only the first element is taken. When supplying binary data, the appropriate 'Content-Type' header should be set to specify the binary format.
response: (optional) a character vector specifying the response headers to return e.g. c("date", "server"). These are case-insensitive and will return NULL if not present. Specify TRUE to return all response headers. A non-character vector will be ignored (other than TRUE).
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.

Public Internet HTTPS

When making HTTPS requests over the public internet, you should supply a TLS configuration to validate server certificates. See tls_config() for details.

Examples

Run this code

s <- ncurl_session(
  "https://postman-echo.com/get",
  response = "date",
  timeout = 2000L
)
s
if (is_ncurl_session(s)) transact(s)
if (is_ncurl_session(s)) close(s)