HTTPRequest

HTTPRequest[url]

represents an HTTP request for the specified URL.

HTTPRequest[assoc]

represents an HTTP request built from the components in the association assoc.

HTTPRequest[url,assoc]

represents an HTTP request for the specified URL with additional elements such as headers given by assoc.

Details and Options

  • HTTPRequest gives a symbolic representation of an HTTP request; it does not execute the request.
  • In HTTPRequest[url], url can be a string, a URL object, or a cloud object.
  • The URL can also be specified by giving the following components in an association:
  • "Scheme"URL scheme
    "User"user information
    "Domain"domain name or host
    "Port"port number (as an integer)
    "Path"path list or string
    "Query"query string or list of parameter-value pairs
  • The following additional entries can also be given in the association:
  • Method"GET"method to use for the HTTP request
    "Body"""contents of message body to be sent
    "ContentType"Automaticcontent-type header for the request
    "Username"""username to use for the request
    "Password"""password to use for the request
    "Cookies"Automaticcookies to send to the server
    "UserAgent"Automaticuser agent string to send
    "Headers"{}list of headers to be sent to the server
  • The setting for "Body" can have the following forms:
  • "string"string to be sent literally
    ByteArray[…]byte array to be sent literally
    {b1,b2,b3,…}list of bytes to be sent literally
    {"par1""val1","par2""val2",…}list of parameters and values to be sent URL encoded
    {"par1"{"val11",…},…}list with multiple values associated with a single parameter
    <|"key1"val1,"key2"val2,…|>alternative form for list of parameters and values
    {"par1"File[…],"par2"File[…],…}files to be sent with multipart encoding
    {"par1"assoc1,…}multipart encoding with detailed specifications for each part
  • Detailed specifications for each part in a multipart encoding are given as an association with the following elements:
  • "Content"the content, as a string, byte array, file object, etc.
    "Name"the name to assign to the part
    "MIMEType"the MIME type to assign to the part
  • The setting "Cookies"->Automatic specifies that cookies from $Cookies for the domain corresponding to url should be sent. "Cookies" can also give an explicit list of associations representing cookies.
  • The setting for "Headers" can be a list of rules or an association.
  • The default "UserAgent" is typically "Wolfram HTTPClient xxxx", where xxxx is a version number.
  • HTTPRequest supports the following options:
  • CharacterEncodingAutomaticcharacter encoding for strings sent
    CookieFunction Automaticfunction to apply to each cookie received
    FollowRedirects Truewhether to follow HTTP redirects
    InteractiveTruewhether to allow interactive authentication dialogs
    TimeConstraint Infinitytime to wait for a response
    VerifySecurityCertificates Truewhether to verify SSL security certificates
  • The setting CharacterEncoding->"enc" specifies that all strings that appear in the request should be encoded using the encoding enc before being sent to the server.
  • The setting CharacterEncoding->None specifies that no change should be made to strings before sending them to the server.
  • With CharacterEncoding->Automatic, the encoding is taken from the "ContentType" element if this is specified; otherwise the encoding is "UTF8".
  • TimeConstraint->t allows a maximum of t seconds for connection to the URL specified in the HTTP request, and reading from it.
  • TimeConstraint-><|"Connecting"->tc,"Reading"->tr|> specifies separate timeouts for connecting to the URL, and reading from it.
  • HTTPRequest[…]["prop"] extracts the value for the property prop of the HTTP request.
  • Possible properties include all components and additional elements, as well as:
  • "Body"body of the request as a string
    "BodyByteArray"raw body of the request as a ByteArray object
    "BodyBytes"raw body of the request as a list of byte values
    "FormRules"rules for all form elements in the request
    "PathString"complete path as a string
    "QueryString"complete query string
    "AbsolutePath"complete path as a string, including scheme and domain
    "AbsoluteDomain"complete domain as a string, including scheme
    "Properties"list of all possible properties
    "PropertyAssociation"association giving values of all properties

Examples

open allclose all

Basic Examples  (1)

Define an HTTPRequest:

Get an HTTPResponse using URLRead:

Extract metadata from the request:

Scope  (2)

Build a URL from components:

Changing query parameters and scheme for a given URL:

To specify parameters with the same name, you can use a list of rules:

Or they can be grouped in a list:

Grouping parameters in a list is useful when working with associations, since they do not allow repeated keys:

If no Method is specified, "GET" is used automatically:

The body can be a raw string:

To send an HTTP request where the body is URL encoded, you can just send a list of values. If no Method is specified, "POST" is used automatically:

To send files, just use the file object:

To send a more complex file specification, you can use Association:

Content in the Association can be a string, a ByteArray, or a File:

Options  (4)

VerifySecurityCertificates  (1)

Verify that the SSL certificate used by the server is valid:

CookieFunction  (1)

Print each cookie that is returned in the HTTP response:

TimeConstraint  (1)

Specify the maximum allotted time in seconds to finish downloading data from the server:

FollowRedirects  (1)

Specify whether to follow HTTP redirects when retrieving a URL:

Properties & Relations  (2)

File and CloudObject are fully supported:

Use URLDownload to store output in a file:

Import the request by using Import or URLExecute:

Possible Issues  (1)

Network requests can go wrong for several reasons; messages are sent to help you debug possible causes, and a Failure object is returned:

The Failure object contains the HTTPRequest object:

Neat Examples  (1)

Import an APIFunction:

Wolfram Research (2016), HTTPRequest, Wolfram Language function, https://reference.wolfram.com/language/ref/HTTPRequest.html.

Text

Wolfram Research (2016), HTTPRequest, Wolfram Language function, https://reference.wolfram.com/language/ref/HTTPRequest.html.

CMS

Wolfram Language. 2016. "HTTPRequest." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/HTTPRequest.html.

APA

Wolfram Language. (2016). HTTPRequest. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/HTTPRequest.html

BibTeX

@misc{reference.wolfram_2024_httprequest, author="Wolfram Research", title="{HTTPRequest}", year="2016", howpublished="\url{https://reference.wolfram.com/language/ref/HTTPRequest.html}", note=[Accessed: 21-November-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_httprequest, organization={Wolfram Research}, title={HTTPRequest}, year={2016}, url={https://reference.wolfram.com/language/ref/HTTPRequest.html}, note=[Accessed: 21-November-2024 ]}