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