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)
the URL address.
[default TRUE] logical value whether to attempt conversion of the received raw bytes to a character vector. Supplying a non-logical value will error.
(optional) the HTTP method (defaults to 'GET' if not specified).
(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.
(optional) the request data to be submitted.
(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.
(optional) integer value in milliseconds after which the connection and subsequent transact attempts time out.
(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.
an 'ncurlSession' object.
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.
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)