ncurl

Source: R/ncurl.R

nano cURL - a minimalist http(s) client.

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

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.

follow

[default FALSE] logical value whether to automatically follow redirects (not applicable for async requests). If FALSE, the redirect address is returned as response header 'Location'.

method

(optional) the HTTP method (defaults to 'GET' if not specified).

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 request data to be submitted.

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

Value

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

  • $data - the response body, as a character string if 'convert' = TRUE (may be further parsed as html, json, xml etc. as required), or a raw byte vector if FALSE (use writeBin to save as a file).

See also

ncurl_aio for asynchronous http requests; ncurl_session for persistent connections.

Examples

ncurl("https://postman-echo.com/get",
       convert = FALSE,
       response = c("date", "content-type"),
       timeout = 1200L)
#> $status
#> [1] 200
#> 
#> $headers
#> $headers$date
#> [1] "Fri, 26 Apr 2024 19:44:51 GMT"
#> 
#> $headers$`content-type`
#> [1] "application/json; charset=utf-8"
#> 
#> 
#> $data
#>   [1] 7b 0a 20 20 22 61 72 67 73 22 3a 20 7b 7d 2c 0a 20 20 22 68 65 61 64 65 72
#>  [26] 73 22 3a 20 7b 0a 20 20 20 20 22 78 2d 66 6f 72 77 61 72 64 65 64 2d 70 72
#>  [51] 6f 74 6f 22 3a 20 22 68 74 74 70 73 22 2c 0a 20 20 20 20 22 78 2d 66 6f 72
#>  [76] 77 61 72 64 65 64 2d 70 6f 72 74 22 3a 20 22 34 34 33 22 2c 0a 20 20 20 20
#> [101] 22 68 6f 73 74 22 3a 20 22 70 6f 73 74 6d 61 6e 2d 65 63 68 6f 2e 63 6f 6d
#> [126] 22 2c 0a 20 20 20 20 22 78 2d 61 6d 7a 6e 2d 74 72 61 63 65 2d 69 64 22 3a
#> [151] 20 22 52 6f 6f 74 3d 31 2d 36 36 32 63 30 34 33 33 2d 31 33 36 63 39 32 32
#> [176] 32 34 37 31 65 35 63 33 63 34 36 66 39 34 34 64 63 22 0a 20 20 7d 2c 0a 20
#> [201] 20 22 75 72 6c 22 3a 20 22 68 74 74 70 73 3a 2f 2f 70 6f 73 74 6d 61 6e 2d
#> [226] 65 63 68 6f 2e 63 6f 6d 2f 67 65 74 22 0a 7d
#> 
ncurl("https://postman-echo.com/put",
      method = "PUT",
      headers = c(Authorization = "Bearer APIKEY"),
      data = "hello world",
      timeout = 1500L)
#> $status
#> [1] 200
#> 
#> $headers
#> NULL
#> 
#> $data
#> [1] "{\n  \"args\": {},\n  \"data\": \"hello world\",\n  \"files\": {},\n  \"form\": {},\n  \"headers\": {\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"host\": \"postman-echo.com\",\n    \"x-amzn-trace-id\": \"Root=1-662c0433-76a738ff36bd38fc363c253c\",\n    \"content-length\": \"11\",\n    \"authorization\": \"Bearer APIKEY\",\n    \"content-type\": \"application/json\"\n  },\n  \"json\": null,\n  \"url\": \"https://postman-echo.com/put\"\n}"
#> 
ncurl("https://postman-echo.com/post",
      method = "POST",
      headers = c(`Content-Type` = "application/json"),
      data = '{"key":"value"}',
      timeout = 1500L)
#> $status
#> [1] 200
#> 
#> $headers
#> NULL
#> 
#> $data
#> [1] "{\n  \"args\": {},\n  \"data\": {\n    \"key\": \"value\"\n  },\n  \"files\": {},\n  \"form\": {},\n  \"headers\": {\n    \"x-forwarded-proto\": \"https\",\n    \"x-forwarded-port\": \"443\",\n    \"host\": \"postman-echo.com\",\n    \"x-amzn-trace-id\": \"Root=1-662c0433-04b1a92714d642b0096c41e9\",\n    \"content-length\": \"15\",\n    \"content-type\": \"application/json\"\n  },\n  \"json\": {\n    \"key\": \"value\"\n  },\n  \"url\": \"https://postman-echo.com/post\"\n}"
#>