The HttpRequest class allows you to make GET, POST, PUT, and DELETE requests to an HTTP or HTTPS server.

Example

Make a request to a server and retrieve the status code, the response headers, and the response text body:

response = HttpRequest.Get('https://httpbin.org/')
print, response.status_code
print, response.headers, /implied
print, response.text

IDL prints:

200
{
  "content-type": "text/html; charset=utf-8",
  "content-length": "9593"
}
<!DOCTYPE html>
<html lang="en">
  ...
</html>

For more examples see HttpRequest Examples.

Methods

HttpRequest::Get

The HttpRequest::Get static method sends a GET request to a server.

Syntax

Obj = HttpRequest.Get(URL, CALLBACK_FUNCTION=string, CALLBACK_DATA=value, /ESCAPE, HEADERS=value, OPTIONS=value, PARAMS=value)

Return Value

This static method returns an HttpRequest object containing the response. The object has the following properties:

  • CONTENT - A byte array containing the raw data from the response body (or a scalar 0 if an error occurred).

  • HEADERS - An OrderedHash containing the response headers as key/value pairs (or an empty hash if an error occurred).

  • OK - A boolean (true/false) that indicates whether the request was successful (status code ≥ 100 and < 400).

  • STATUS_CODE - An integer containing the HTTP status code, such as 200, 302, 401, etc. STATUS_CODE < 100 indicates an error.

  • TEXT - A scalar string containing the request result (or the error message if an error occurred).

  • URL - A scalar string containing the final URL, including parameters or redirects.

  • JSON() - Call this method to return the parsed JSON response. See HttpRequest::Json for details.

See HttpRequest Properties for details and additional properties.

Arguments

URL

Set this keyword equal to a string containing the URL of the request.

Keywords

CALLBACK_FUNCTION

Set this keyword to a string containing the name of an IDL function. The function should have the form:

function mycallback, downTotal, downNow, upTotal, upNow, callbackData

The callback arguments are:

  • downTotal - an integer giving the total number of bytes that HttpRequest expects to download.

  • downNow - an integer giving the number of bytes that HttpRequest has downloaded so far.

  • upTotal - an integer giving the total number of bytes that HttpRequest expects to upload.

  • upNow - an integer giving the number of bytes that HttpRequest has uploaded so far.

  • callbackData - an argument that contains the CALLBACK_DATA value, or undefined if no CALLBACK_DATA was provided.

Your callback function should return 1 to continue the request, or 0 to cancel the request.

Note: IDL may call your callback function while the connection is being made, passing in zero for the download and upload values. In addition, some URLs may not provide the total download size and will always return zero for downTotal. Your callback function should be written with these special cases in mind.

For callback examples see HttpRequest Examples.

CALLBACK_DATA

Set this keyword to an IDL variable of any type. This value will be passed back as the fifth argument to the callback function, but is otherwise ignored by the Get method. If you do not set this keyword, the callbackData argument will be passed in as an undefined variable.

ESCAPE

If this keyword is set, and PARAMS is a hash or dictionary, then each of the keys and values is URL encoded. All characters that are not a–z, A–Z, 0–9, '-', '.', '_' or '~' are URL-escaped (%NN). If PARAMS is a string array or scalar string then this keyword is ignored.

HEADERS

Set this keyword equal to a hash, dictionary, or structure of key/value pairs containing HTTP request headers. For example, to send the header "Authorization: Basic Zm9vOmJhcg==", you would set headers = {Authorization: "Basic Zm9vOmJhcg=="}.

OPTIONS

Set this keyword equal to a hash, dictionary, or structure of key/value pairs containing CURL options for the request. For example, to set the TIMEOUT option to 180 seconds, you would set options = {TIMEOUT: 180}. See HttpRequest Options for a list of available options.

PARAMS

Set this keyword equal to a hash, dictionary, string array, or scalar string containing HTTP GET parameters.

  • If PARAMS is a hash or dictionary, the key/value pairs will be appended to the URL as ?key1=value1&key2=value2&.... The ESCAPE keyword may be used to automatically escape (URL encode) any special characters.

  • If PARAMS is a string array, each element should contain a parameter in the form "key=value". These will be combined together using "&" as a separator and appended to the URL along with the "?" separator. The ESCAPE keyword is ignored.

  • If PARAMS is a scalar string, it is assumed to already be in the form key1=value1&key2=value2&.... This string will be appended to the URL along with the "?" separator. The ESCAPE keyword is ignored.

For example, to perform a search for the term "idl software":

IDL> result = HttpRequest.Get("https://google.com", PARAMS=hash("q", "idl software"), /ESCAPE)
IDL> print, result.url
https://www.google.com/?q=idl%20software

Note that we use the /ESCAPE keyword since our parameter value contains a space character.

For more examples see HttpRequest Examples.

HttpRequest::Post

The HttpRequest::Post static method sends a POST request to a server.

Syntax

Obj = HttpRequest.Post(URL, CALLBACK_FUNCTION=string, CALLBACK_DATA=value, DATA=value, /ESCAPE, HEADERS=value, JSON=value, MULTIPART=value, OPTIONS=value, PARAMS=value)

Return Value

This static method returns an HttpRequest object containing the response. The object has the following properties:

  • CONTENT - A byte array containing the raw data from the response body (or a scalar 0 if an error occurred).

  • HEADERS - An OrderedHash containing the response headers as key/value pairs (or an empty hash if an error occurred).

  • OK - A boolean (true/false) that indicates whether the request was successful (status code ≥ 100 and < 400).

  • STATUS_CODE - An integer containing the HTTP status code, such as 200, 302, 401, etc. STATUS_CODE < 100 indicates an error.

  • TEXT - A scalar string containing the request result (or the error message if an error occurred).

  • URL - A scalar string containing the final URL, including parameters or redirects.

  • JSON() - Call this method to return the parsed JSON response. See HttpRequest::Json for details.

See HttpRequest Properties for details and additional properties.

Arguments

URL

Set this keyword equal to a string containing the URL of the request.

Keywords

CALLBACK_FUNCTION

Set this keyword to a string containing the name of an IDL function. The function should have the form:

function mycallback, downTotal, downNow, upTotal, upNow [, callbackData]

The callback arguments are:

  • downTotal - an integer giving the total number of bytes that HttpRequest expects to download.

  • downNow - an integer giving the number of bytes that HttpRequest has downloaded so far.

  • upTotal - an integer giving the total number of bytes that HttpRequest expects to upload.

  • upNow - an integer giving the number of bytes that HttpRequest has uploaded so far.

  • callbackData - an argument that contains the CALLBACK_DATA value, or undefined if no CALLBACK_DATA was provided.

Your callback function should return 1 to continue the request, or 0 to cancel the request.

Note: IDL may call your callback function while the connection is being made, passing in zero for the download and upload values. In addition, some URLs may not provide the total download size and will always return zero for downTotal. Your callback function should be written with these special cases in mind.

For callback examples see HttpRequest Examples.

CALLBACK_DATA

Set this keyword to an IDL variable of any type. This value will be passed back as the fifth argument to the callback function, but is otherwise ignored by the Get method. If you do not set this keyword, the callbackData argument will be passed in as an undefined variable.

DATA

Set this keyword to a byte array containing a binary data payload to be sent to the server. By default the bytes will be sent using the application/octet-stream content type. You can change the content type using the HEADERS keyword.

ESCAPE

If this keyword is set, and PARAMS is a hash or dictionary, then each of the keys and values is URL encoded. All characters that are not a–z, A–Z, 0–9, '-', '.', '_' or '~' are URL-escaped (%NN). If PARAMS is a string array or scalar string then this keyword is ignored.

JSON

Set this keyword to send JSON-encoded data using the application/json content type. If JSON is a scalar string then it will be assumed to already be JSON and will be sent unmodified. If JSON is any other IDL variable type, it will be passed through the JSON_SERIALIZE function first.

HEADERS

Set this keyword equal to a hash, dictionary, or structure of name/value pairs containing HTTP request headers. For example, to send the header "Authorization: Basic Zm9vOmJhcg==", you would set headers = {Authorization: "Basic Zm9vOmJhcg=="}. As another example, to change the content-type, you could set headers = hash("Content-type", "image/jpeg"). If you set the value to a null (empty) string then that header name will be deleted from the request. If the header name ends in a semicolon, then the header name will be sent with an empty value.

MULTIPART

Set this keyword to a hash of key/value pairs containing parameter names and values. This data will be sent using the multipart/form-data content type, where each key/value pair is sent as a separate part, separated by a boundary string. If value is a scalar string or byte array, it will be sent unchanged.

Value can instead be set to an IDL structure with one or more of the following fields:

Field name

Data
VALUE

A scalar string or byte array containing the data. Either VALUE or FILE must be specified.
FILE A scalar string containing the filepath to a file to upload. Either VALUE or FILE must be specified.

MIMETYPE

An optional scalar string containing the mime type. If not provided then no mime type will be sent.
HEADERS

An optional hash, dictionary, or structure of key/value pairs containing additional headers for this part.

For example, here we upload two text parameters and a parameter containing a file:

resume = {file: 'resume.pdf', mimetype: 'application/pdf'}
multipart = hash("name", "David Stern", "job", "Engineer", "resume", resume}
a = HttpRequest.Post(url, multipart=multipart)

For more examples see HttpRequest Examples.

OPTIONS

Set this keyword equal to a hash, dictionary, or structure of key/value pairs containing CURL options for the request. For example, to set the TIMEOUT option to 180 seconds, you would set options = {TIMEOUT: 180}.

PARAMS

Set this keyword equal to a hash, dictionary, string array, or scalar string containing parameters to be sent using the application/x-www-form-urlencoded content type.

  • If PARAMS is a hash or dictionary, the key/value pairs will be combined together and sent as ?key1=value1&key2=value2&.... The ESCAPE keyword may be used to automatically escape (URL encode) any special characters.

  • If PARAMS is a string array, each element should contain a parameter in the form "key=value". These will be combined together using "&" as a separator. The ESCAPE keyword is ignored.

  • If PARAMS is a scalar string, it is assumed to already be in the form key1=value1&key2=value2&.... The ESCAPE keyword is ignored.

HttpRequest::Put

The HttpRequest::Put static method sends a PUT request to a server.

Syntax

Obj = HttpRequest.Put(URL, CALLBACK_FUNCTION=string, CALLBACK_DATA=value, DATA=value, /ESCAPE, HEADERS=value, JSON=value, MULTIPART=value, OPTIONS=value, PARAMS=value)

Return Value

See HttpRequest::Post for a description of the result.

Arguments

URL

Set this keyword equal to a string containing the URL of the request.

Keywords

See HttpRequest::Post for a description of the keywords.

HttpRequest::Delete

The HttpRequest::Delete static method sends a DELETE request to a server.

Syntax

Obj = HttpRequest.Delete(URL, CALLBACK_FUNCTION=string, CALLBACK_DATA=value, HEADERS=value, OPTIONS=value)

Return Value

See HttpRequest::Post for a description of the result.

Arguments

URL

Set this keyword equal to a string containing the URL of the request.

Keywords

See HttpRequest::Post for a description of the keywords.

HttpRequest::Escape

The HttpRequest::Escape static method can be used to perform URL encoding on a scalar string or byte array. All characters that are not a–z, A–Z, 0–9, '-', '.', '_' or '~' are URL-escaped with %NN, where NN is the equivalent hex code.

Syntax

Obj = HttpRequest.Escape(Value)

Return Value

This method returns a scalar string.

Arguments

String

Set this argument to a scalar string or byte array containing the characters to be encoded.

Keywords

None

HttpRequest::Unescape

The HttpRequest::Unescape static method can be used to perform URL decoding on a scalar string. Any sequences of the form %NN (where NN is a hex code) are converted back to their equivalent character.

Syntax

Obj = HttpRequest.Unescape(Value)

Return Value

This method returns a scalar string.

Arguments

String

Set this argument to a scalar string to be decoded.

Keywords

None

HttpRequest::Json

After the request finishes, the HttpRequest::Json method can be used to parse the JSON-encoded response body.

Note: This is the only non-static method to HttpRequest. You must have a valid HttpRequest object (from a call to Get, Post, Put, or Delete) to call the Json method.

Syntax

Result = obj.Json(/QUIET, /DICTIONARY, /FOLD_CASE, /TOARRAY, /TOSTRUCT)

Return Value

This method returns either an OrderedHash or a List, depending upon the response body. If the response was not JSON then an error is thrown (unless /QUIET is set).

Keywords

QUIET

Set this keyword to suppress any errors from JSON parsing. If the response was not JSON and /QUIET is set, then a null string will be returned.

DICTIONARY, FOLD_CASE, TOARRAY, TOSTRUCT

See JSON_PARSE for a description of these keywords.

Version History

9.0

Introduced

See Also

HttpRequest Examples, HttpRequest Options, HttpRequest Properties