POST file to a server.

Source: R/http-post.r

POST file to a server.

POST(
  url = NULL,
  config = list(),
  ...,
  body = NULL,
  encode = c("multipart", "form", "json", "raw"),
  handle = NULL
)

Arguments

url

the url of the page to retrieve
config

Additional configuration settings such as http authentication (authenticate()), additional headers (add_headers()), cookies (set_cookies()) etc. See config() for full details and list of helpers.
...

Further named parameters, such as query, path, etc, passed on to modify_url(). Unnamed parameters will be combined with config().
body

One of the following:

  • FALSE: No body. This is typically not used with POST, PUT, or PATCH, but can be useful if you need to send a bodyless request (like GET) with VERB().

  • NULL: An empty body

  • "": A length 0 body

  • upload_file("path/"): The contents of a file. The mime type will be guessed from the extension, or can be supplied explicitly as the second argument to upload_file()

  • A character or raw vector: sent as is in body. Use content_type() to tell the server what sort of data you are sending.

  • A named list: See details for encode.
encode

If the body is a named list, how should it be encoded? Can be one of form (application/x-www-form-urlencoded), multipart, (multipart/form-data), or json (application/json).

For "multipart", list elements can be strings or objects created by upload_file(). For "form", elements are coerced to strings and escaped, use I() to prevent double-escaping. For "json", parameters are automatically "unboxed" (i.e. length 1 vectors are converted to scalars). To preserve a length 1 vector as a vector, wrap in I(). For "raw", either a character or raw vector. You'll need to make sure to set the content_type() yourself.
handle

The handle to use with this request. If not supplied, will be retrieved and reused from the handle_pool() based on the scheme, hostname and port of the url. By default httr requests to the same scheme/host/port combo. This substantially reduces connection time, and ensures that cookies are maintained over multiple requests to the same host. See handle_pool() for more details.

Value

A response() object.

See also

Other http methods: BROWSE(), DELETE(), GET(), HEAD(), PATCH(), PUT(), VERB()

Examples

b2 <- "http://httpbin.org/post"
POST(b2, body = "A simple text string")
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 479 B
#> {
#>   "args": {}, 
#>   "data": "A simple text string", 
#>   "files": {}, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#>     "Content-Length": "20", 
#>     "Host": "httpbin.org", 
#> ...
POST(b2, body = list(x = "A simple text string"))
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 590 B
#> {
#>   "args": {}, 
#>   "data": "", 
#>   "files": {}, 
#>   "form": {
#>     "x": "A simple text string"
#>   }, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#> ...
POST(b2, body = list(y = upload_file(system.file("CITATION"))))
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 1.6 kB
#> {
#>   "args": {}, 
#>   "data": "", 
#>   "files": {
#>     "y": "bibentry(\"Manual\",\n         title = \"R: A Language and Environm...
#>   }, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#> ...
POST(b2, body = list(x = "A simple text string"), encode = "json")
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 565 B
#> {
#>   "args": {}, 
#>   "data": "{\"x\":\"A simple text string\"}", 
#>   "files": {}, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#>     "Content-Length": "28", 
#>     "Content-Type": "application/json", 
#> ...

# body can also be provided as a json string directly to deal
# with specific case, like an empty element in the json string.
# passing as string directly
POST(b2, body = '{"a":1,"b":{}}', encode = "raw")
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 503 B
#> {
#>   "args": {}, 
#>   "data": "{\"a\":1,\"b\":{}}", 
#>   "files": {}, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#>     "Content-Length": "14", 
#>     "Host": "httpbin.org", 
#> ...
# or building the json string before
json_body <- jsonlite::toJSON(list(a = 1, b = NULL), auto_unbox = TRUE)
POST(b2, body = json_body, encode = "raw")
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 503 B
#> {
#>   "args": {}, 
#>   "data": "{\"a\":1,\"b\":{}}", 
#>   "files": {}, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#>     "Content-Length": "14", 
#>     "Host": "httpbin.org", 
#> ...

# Various types of empty body:
POST(b2, body = NULL, verbose())
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 458 B
#> {
#>   "args": {}, 
#>   "data": "", 
#>   "files": {}, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#>     "Content-Length": "0", 
#>     "Host": "httpbin.org", 
#> ...
POST(b2, body = FALSE, verbose())
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 405
#>   Content-Type: text/html
#> <EMPTY BODY>
POST(b2, body = "", verbose())
#> Response [http://httpbin.org/post]
#>   Date: 2020-08-17 22:22
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 458 B
#> {
#>   "args": {}, 
#>   "data": "", 
#>   "files": {}, 
#>   "form": {}, 
#>   "headers": {
#>     "Accept": "application/json, text/xml, application/xml, */*", 
#>     "Accept-Encoding": "deflate, gzip", 
#>     "Content-Length": "0", 
#>     "Host": "httpbin.org", 
#> ...