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


Note: You cannot directly instantiate an HttpRequest object: calling Obj_New or HttpRequest( ) will generate an error. Instead, to generate an HttpRequest object, you should call one of the four static methods: HttpRequest::Get, HttpRequest::Post, HttpRequest::Put, or HttpRequest::Delete.

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, /PROGRESS)

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.

PROGRESS_BAR

If this keyword is set, then HttpRequest will display the request progress using a progress bar on the IDL command line.

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, /PROGRESS)

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. Each value must be one of the following types:

Value type

Note

Byte array

Sent as a string of bytes

String Sent as a string

Hash or dictionary

Converted to a string using json_serialize

Structure

Used to send files or additional options; see below for details

If the value is an IDL structure, you can pass a filename and specify additional information such as the mimetype or optional headers. The structure should have one or more of the following fields:

Field name

Data

VALUE

A scalar string, byte array, hash, or dictionary containing the data. If VALUE is a hash or dictionary, it will be converted to a string using json_serialize. 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.

PROGRESS_BAR

If this keyword is set, then HttpRequest will display the request progress using a progress bar on the IDL command line.

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, /PROGRESS_BAR, HEADERS=value, JSON=value, MULTIPART=value, OPTIONS=value, PARAMS=value, /PROGRESS)

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, /PROGRESS_BAR, 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

9.1

For MULTIPART, pass hash/dictionary values as json serialized strings. Add PROGRESS_BAR keyword to ::Get, ::Post, and ::Put.

See Also


HttpRequest Examples, HttpRequest Options, HttpRequest Properties