Skip to contents

ncurl Session

Source: R/ncurl.R
ncurl_session.Rd

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 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) character string request data to be submitted. If a vector, only the first element is taken, and non-character objects are ignored.

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. A non-character vector will be ignored.

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.

See also

ncurl_aio for asynchronous http requests.

Examples

s <- ncurl_session("https://postman-echo.com/get",
                   response = "date",
                   timeout = 2000L)
s
#> < ncurlSession > - transact() to return data
if (is_ncurl_session(s)) transact(s)
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Mon, 18 Nov 2024 10:37:50 GMT"
#> 
#> 
#> $data
#> [1] "{\n  \"args\": {},\n  \"headers\": {\n    \"host\": \"postman-echo.com\",\n    \"x-request-start\": \"t=1731926270.261\",\n    \"connection\": \"close\",\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"x-amzn-trace-id\": \"Root=1-673b18fe-6f69344b1201a9801a0ab923\"\n  },\n  \"url\": \"https://postman-echo.com/get\"\n}"
#> 
if (is_ncurl_session(s)) close(s)