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.

ncurl_session(
  url,
  convert = TRUE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  pem = 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. Supplying a non-logical value will error.

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

pem

(optional) applicable to secure HTTPS sites only. The path to a file containing X.509 certificate(s) in PEM format, comprising the certificate authority certificate chain (and revocation list if present). 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 4 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.

  • $raw - raw vector of the received resource (use writeBin to save to a file).

  • $data - converted character string (if specified in the session), or NULL otherwise. This may be further parsed this as html, json, xml etc. if required.

Examples

s <- ncurl_session("https://httpbin.org/get", response = "date", timeout = 1000L)
s
#> < ncurlSession >
#>  - use transact() to return data
if (!is_error_value(s)) transact(s)
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Tue, 28 Mar 2023 09:51:11 GMT"
#> 
#> 
#> $raw
#>   [1] 7b 0a 20 20 22 61 72 67 73 22 3a 20 7b 7d 2c 20 0a 20 20 22 68 65 61 64 65
#>  [26] 72 73 22 3a 20 7b 0a 20 20 20 20 22 48 6f 73 74 22 3a 20 22 68 74 74 70 62
#>  [51] 69 6e 2e 6f 72 67 22 2c 20 0a 20 20 20 20 22 58 2d 41 6d 7a 6e 2d 54 72 61
#>  [76] 63 65 2d 49 64 22 3a 20 22 52 6f 6f 74 3d 31 2d 36 34 32 32 62 38 38 66 2d
#> [101] 30 36 32 37 37 66 31 35 33 61 32 39 62 33 35 35 36 34 32 31 36 34 38 30 22
#> [126] 0a 20 20 7d 2c 20 0a 20 20 22 6f 72 69 67 69 6e 22 3a 20 22 35 32 2e 32 32
#> [151] 36 2e 31 32 36 2e 32 33 31 22 2c 20 0a 20 20 22 75 72 6c 22 3a 20 22 68 74
#> [176] 74 70 73 3a 2f 2f 68 74 74 70 62 69 6e 2e 6f 72 67 2f 67 65 74 22 0a 7d 0a
#> 
#> $data
#> [1] "{\n  \"args\": {}, \n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-6422b88f-06277f153a29b35564216480\"\n  }, \n  \"origin\": \"52.226.126.231\", \n  \"url\": \"https://httpbin.org/get\"\n}\n"
#> 
if (!is_error_value(s)) close(s)