ncurl

nano cURL - a minimalist http(s) client.

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

Arguments

url

the URL address.

async

[default FALSE] logical value whether to perform actions async.

convert

[default TRUE] logical value whether to attempt conversion of the received raw bytes to a character vector.

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

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.

follow

(optional) logical TRUE or FALSE whether to automatically follow redirects. If missing or NULL, the default is not to follow redirects, or prompt in interactive environments.

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.

Value

Named list of 4 elements:

• $status - integer HTTP repsonse status code (200 - OK).

• $headers - named list of response headers supplied in 'response' or NULL if unspecified.

• $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').

Redirects

In interactive sessions: will prompt upon receiving a redirect location whether to follow or not (default: yes).

In non-interactive sessions: redirects are never followed.

The above defaults can be overridden by specifying TRUE or FALSE for the argument 'follow'.

If not followed, the redirect address is returned as a character string.

For async requests, the redirect address will be returned as a character string at $raw and $data will be NULL.

Examples

ncurl("https://httpbin.org/get", response = c("date", "server"))
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Mon, 26 Sep 2022 22:57:44 GMT"
#> 
#> $headers$server
#> [1] "gunicorn/19.9.0"
#> 
#> 
#> $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 33 33 32 32 65 36 38 2d
#> [101] 30 31 64 35 33 61 38 64 34 65 66 33 33 66 38 39 34 32 32 39 61 31 66 38 22
#> [126] 0a 20 20 7d 2c 20 0a 20 20 22 6f 72 69 67 69 6e 22 3a 20 22 32 30 2e 31 32
#> [151] 2e 32 2e 39 36 22 2c 20 0a 20 20 22 75 72 6c 22 3a 20 22 68 74 74 70 73 3a
#> [176] 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-63322e68-01d53a8d4ef33f894229a1f8\"\n  }, \n  \"origin\": \"20.12.2.96\", \n  \"url\": \"https://httpbin.org/get\"\n}\n"
#> 
ncurl("http://httpbin.org/put",,,"PUT", list(Authorization = "Bearer APIKEY"), "hello world")
#> $status
#> [1] 200
#> 
#> $headers
#> NULL
#> 
#> $raw
#>   [1] 7b 0a 20 20 22 61 72 67 73 22 3a 20 7b 7d 2c 20 0a 20 20 22 64 61 74 61 22
#>  [26] 3a 20 22 68 65 6c 6c 6f 20 77 6f 72 6c 64 22 2c 20 0a 20 20 22 66 69 6c 65
#>  [51] 73 22 3a 20 7b 7d 2c 20 0a 20 20 22 66 6f 72 6d 22 3a 20 7b 7d 2c 20 0a 20
#>  [76] 20 22 68 65 61 64 65 72 73 22 3a 20 7b 0a 20 20 20 20 22 41 75 74 68 6f 72
#> [101] 69 7a 61 74 69 6f 6e 22 3a 20 22 42 65 61 72 65 72 20 41 50 49 4b 45 59 22
#> [126] 2c 20 0a 20 20 20 20 22 43 6f 6e 74 65 6e 74 2d 4c 65 6e 67 74 68 22 3a 20
#> [151] 22 31 31 22 2c 20 0a 20 20 20 20 22 48 6f 73 74 22 3a 20 22 68 74 74 70 62
#> [176] 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
#> [201] 63 65 2d 49 64 22 3a 20 22 52 6f 6f 74 3d 31 2d 36 33 33 32 32 65 36 38 2d
#> [226] 34 62 63 37 62 63 37 63 33 66 64 37 34 66 61 37 32 33 35 35 61 36 38 35 22
#> [251] 0a 20 20 7d 2c 20 0a 20 20 22 6a 73 6f 6e 22 3a 20 6e 75 6c 6c 2c 20 0a 20
#> [276] 20 22 6f 72 69 67 69 6e 22 3a 20 22 32 30 2e 31 32 2e 32 2e 39 36 22 2c 20
#> [301] 0a 20 20 22 75 72 6c 22 3a 20 22 68 74 74 70 3a 2f 2f 68 74 74 70 62 69 6e
#> [326] 2e 6f 72 67 2f 70 75 74 22 0a 7d 0a
#> 
#> $data
#> [1] "{\n  \"args\": {}, \n  \"data\": \"hello world\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Authorization\": \"Bearer APIKEY\", \n    \"Content-Length\": \"11\", \n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-63322e68-4bc7bc7c3fd74fa72355a685\"\n  }, \n  \"json\": null, \n  \"origin\": \"20.12.2.96\", \n  \"url\": \"http://httpbin.org/put\"\n}\n"
#> 
ncurl("http://httpbin.org/post",,,"POST", c(`Content-Type` = "application/json"),'{"k":"v"}')
#> $status
#> [1] 200
#> 
#> $headers
#> NULL
#> 
#> $raw
#>   [1] 7b 0a 20 20 22 61 72 67 73 22 3a 20 7b 7d 2c 20 0a 20 20 22 64 61 74 61 22
#>  [26] 3a 20 22 7b 5c 22 6b 5c 22 3a 5c 22 76 5c 22 7d 22 2c 20 0a 20 20 22 66 69
#>  [51] 6c 65 73 22 3a 20 7b 7d 2c 20 0a 20 20 22 66 6f 72 6d 22 3a 20 7b 7d 2c 20
#>  [76] 0a 20 20 22 68 65 61 64 65 72 73 22 3a 20 7b 0a 20 20 20 20 22 43 6f 6e 74
#> [101] 65 6e 74 2d 4c 65 6e 67 74 68 22 3a 20 22 39 22 2c 20 0a 20 20 20 20 22 43
#> [126] 6f 6e 74 65 6e 74 2d 54 79 70 65 22 3a 20 22 61 70 70 6c 69 63 61 74 69 6f
#> [151] 6e 2f 6a 73 6f 6e 22 2c 20 0a 20 20 20 20 22 48 6f 73 74 22 3a 20 22 68 74
#> [176] 74 70 62 69 6e 2e 6f 72 67 22 2c 20 0a 20 20 20 20 22 58 2d 41 6d 7a 6e 2d
#> [201] 54 72 61 63 65 2d 49 64 22 3a 20 22 52 6f 6f 74 3d 31 2d 36 33 33 32 32 65
#> [226] 36 38 2d 36 30 61 63 34 33 37 36 36 61 32 35 66 37 35 33 33 30 63 37 66 64
#> [251] 66 66 22 0a 20 20 7d 2c 20 0a 20 20 22 6a 73 6f 6e 22 3a 20 7b 0a 20 20 20
#> [276] 20 22 6b 22 3a 20 22 76 22 0a 20 20 7d 2c 20 0a 20 20 22 6f 72 69 67 69 6e
#> [301] 22 3a 20 22 32 30 2e 31 32 2e 32 2e 39 36 22 2c 20 0a 20 20 22 75 72 6c 22
#> [326] 3a 20 22 68 74 74 70 3a 2f 2f 68 74 74 70 62 69 6e 2e 6f 72 67 2f 70 6f 73
#> [351] 74 22 0a 7d 0a
#> 
#> $data
#> [1] "{\n  \"args\": {}, \n  \"data\": \"{\\\"k\\\":\\\"v\\\"}\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Content-Length\": \"9\", \n    \"Content-Type\": \"application/json\", \n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-63322e68-60ac43766a25f75330c7fdff\"\n  }, \n  \"json\": {\n    \"k\": \"v\"\n  }, \n  \"origin\": \"20.12.2.96\", \n  \"url\": \"http://httpbin.org/post\"\n}\n"
#>