nano cURL - a minimalist http(s) client.

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

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.

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

Examples

ncurl("https://httpbin.org/get", response = c("date", "server"))
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Tue, 07 Feb 2023 09:24:40 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 65 32 31 38 64 38 2d
#> [101] 31 66 33 33 31 36 62 30 34 37 33 31 65 31 63 64 31 63 30 30 31 64 38 37 22
#> [126] 0a 20 20 7d 2c 20 0a 20 20 22 6f 72 69 67 69 6e 22 3a 20 22 31 37 32 2e 31
#> [151] 37 36 2e 31 33 37 2e 31 37 37 22 2c 20 0a 20 20 22 75 72 6c 22 3a 20 22 68
#> [176] 74 74 70 73 3a 2f 2f 68 74 74 70 62 69 6e 2e 6f 72 67 2f 67 65 74 22 0a 7d
#> [201] 0a
#> 
#> $data
#> [1] "{\n  \"args\": {}, \n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-63e218d8-1f3316b04731e1cd1c001d87\"\n  }, \n  \"origin\": \"172.176.137.177\", \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 65 32 31 38 64 38 2d
#> [226] 34 63 65 37 62 61 31 35 37 61 65 34 33 66 38 33 34 32 33 62 62 36 30 38 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 31 37 32 2e 31 37 36 2e 31 33 37 2e 31
#> [301] 37 37 22 2c 20 0a 20 20 22 75 72 6c 22 3a 20 22 68 74 74 70 3a 2f 2f 68 74
#> [326] 74 70 62 69 6e 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-63e218d8-4ce7ba157ae43f83423bb608\"\n  }, \n  \"json\": null, \n  \"origin\": \"172.176.137.177\", \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 65 32 31 38
#> [226] 64 39 2d 30 32 61 34 35 37 31 37 36 31 33 65 65 35 65 38 30 64 63 63 38 37
#> [251] 36 35 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 31 37 32 2e 31 37 36 2e 31 33 37 2e 31 37 37 22 2c 20 0a 20 20
#> [326] 22 75 72 6c 22 3a 20 22 68 74 74 70 3a 2f 2f 68 74 74 70 62 69 6e 2e 6f 72
#> [351] 67 2f 70 6f 73 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-63e218d9-02a45717613ee5e80dcc8765\"\n  }, \n  \"json\": {\n    \"k\": \"v\"\n  }, \n  \"origin\": \"172.176.137.177\", \n  \"url\": \"http://httpbin.org/post\"\n}\n"
#>