nanonext (version 0.7.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,
  pem = 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 if unspecified. 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 'convert' = TRUE and content is a recognised text format), or NULL otherwise. Other tools can be used to further parse this 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. 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.

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.

Examples

ncurl("https://httpbin.org/get", response = c("date", "server"))
ncurl("http://httpbin.org/put",,,,"PUT", list(Authorization = "Bearer APIKEY"), "hello world")
ncurl("http://httpbin.org/post",,,,"POST", c(`Content-Type` = "application/json"),'{"k":"v"}')