nanonext (version 0.9.2)

ncurl: ncurl

Description

nano cURL - a minimalist http(s) client.

Usage

ncurl(
  url,
  async = FALSE,
  convert = TRUE,
  follow = FALSE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  tls = NULL
)

Value

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 supplied in 'response', 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 - if 'convert' = FALSE, the raw vector of the received resource, or NULL otherwise (use writeBin to save to a file).

• $data - if 'convert' = TRUE, the converted character string, or NULL otherwise. This may be further parsed as html, json, xml etc. if required.

Or else, if 'async' = TRUE, an 'ncurlAio' (object of class 'ncurlAio' and 'recvAio') (invisibly).

Arguments

url

the URL address.

async

[default FALSE] logical value whether to perform an async request, in which case an 'ncurlAio' is returned instead of a list.

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. Supplying a non-logical value will error.

follow

[default FALSE] logical value whether to automatically follow redirects (not applicable for async requests). If FALSE (or async), the redirect address is returned as response header 'Location'. 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 transaction times out if not yet complete.

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.

Examples

ncurl("https://www.r-project.org/",
       convert = FALSE,
       response = c("date", "server"),
       timeout = 1000L)
ncurl("https://postman-echo.com/put",
      method = "PUT",
      headers = list(Authorization = "Bearer APIKEY"),
      data = "hello world",
      timeout = 1500L)
ncurl("https://postman-echo.com/post",
      method = "POST",
      headers = c(`Content-Type` = "application/json"),
      data = '{"k":"v"}',
      timeout = 1500L)