HTTPRequest

The HTTPRequest class allows you to handle HTTPRequest objects that can be used to configure and send requests to an HTTP server, as well as to process the HTTP server responses.

The HTTPRequest class is available from the 4D class store. You create and send HTTP requests using the 4D.HTTPRequest.new() function, that returns a HTTPRequest object.

Example

Create a MyHttpRequestOptions class for the request options:

constructor(method : string, headers : object, body : string)
	this.method = method
	this.headers = headers
	this.body = body

Function onResponse(request : 4D.HTTPRequest, event : object)
//My onResponse method, if you want to handle the request asynchronously

Function onError(request : 4D.HTTPRequest, event : object)
//My onError method, if you want to handle the request asynchronously

You can now create your request:

var headers : object
headers = newObject()
headers["field1"] = "value1"

var myHttpRequestOptions : cs.MyHttpRequestOptions
myHttpRequestOptions = cs.MyHttpRequestOptions.new("GET", headers, "")

var request : 4D.HTTPRequest
request = 4D.HTTPRequest.new("www.google.com", myHttpRequestOptions)
request.wait() //If you want to handle the request synchronously
//Now you can use request.response to access the result of the request or request.error to check the error that happened.

Functions and properties

An HTTPRequest object is a non-sharable object.

HTTPRequest objects provide the following functions and properties:

4D.HTTPRequest.new( url : string { , options : object } ) : 4D.HTTPRequest    creates and sends a HTTP request to the HTTP server defined in url with the defined options, and returns a 4D.HTTPRequest object
dataType : string    the dataType passed in the options object when calling new(), "auto" if it was omitted
encoding : string    the encoding passed in the options object when calling new(), "UTF-8" if it was omitted
errors : collection    the collection of all the errors if at least one error has been triggered
headers : object    the headers passed in the options object when calling new()
method : string    the method passed in the options object when calling new()
protocol : string    the protocol passed in the options object when calling new()
response : object    the response to the request if it has received at least the status code, undefined otherwise
returnResponseBody : boolean    the returnResponseBody passed in the options object when calling new()
.terminate()    aborts the HTTP request
terminated : boolean    true if the request is terminated (after the call to onTerminate), false otherwise
timeout : number    the timeout passed in the options object when calling new()
url : string    the URL of the HTTP request
.wait( { time : number } ) : HTTPRequestClass    waits for the response from the server

4D.HTTPRequest.new()

4D.HTTPRequest.new( url : string { , options : object } ) : 4D.HTTPRequest

Parameter	Type		Description
url	string	→	URL to which to send the request
options	object	→	Request configuration properties
Result	4D.HTTPRequest	←	New HTTPRequest object

Description

The 4D.HTTPRequest.new() function creates and sends a HTTP request to the HTTP server defined in url with the defined options, and returns a 4D.HTTPRequest object.

The returned 4D.HTTPRequest object is used to process responses from the HTTP server and call functions.

In url, pass the URL where you want to send the request. The syntax to use is:

{http://}[{user}:[{password}]@]host[:{port}][/{path}][?{queryString}]
{https://}[{user}:[{password}]@]host[:{port}][/{path}][?{queryString}]

If you omit the protocol part (http:// or https://), a https request is sent.

For example, you can pass the following strings:

    http://www.myserver.com
    www.myserver.com/path
    http://www.myserver.com/path?name = "jones"
    https://www.myserver.com/login
    http://123.45.67.89:8083
    http://john:smith@123.45.67.89:8083
    http://[2001:0db8:0000:0000:0000:ff00:0042:8329]
    http://[2001:0db8:0000:0000:0000:ff00:0042:8329]:8080/index.html

options parameter

In the options parameter, pass an object that can contain the following properties:

Property	Type	Description	Default
body	variant	Body of the request (required in case of post or put requests). Can be a text, a blob, or an object. The content-type is determined from the type of this property unless it is set inside the headers	undefined
certificatesFolder	folder	Sets the active client certificates folder	undefined
dataType	string	Type of the response body attribute. Values: "text", "blob", "object", or "auto". If "auto", the type of the body content will be deduced from its MIME type (object for JSON, text for text, javascript, xml, http message and url encoded form, blob otherwise)	"auto"
decodeData	boolean	If true, the data received in the onData callback is uncompressed	false
encoding	string	Used only in case of requests with a body (post or put methods). Encoding of the request body content if it's a text, ignored if content-type is set inside the headers	"UTF-8"
headers	object	Headers of the request. Syntax: headers.key = value (value can be a collection if the same key must appear multiple times)	Empty object
method	string	"POST", "GET", or other method	"GET"
minTLSVersion	string	Sets the minimum version of TLS: "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3"	"TLSv1_2"
onData	function	Callback when data from the body is received. It receives two objects as parameters (see below)	undefined
onError	function	Callback when an error occurs. It receives two objects as parameters (see below)	undefined
onHeaders	function	Callback when the headers are received. It receives two objects as parameters (see below)	undefined
onResponse	function	Callback when a response is received. It receives two objects as parameters (see below)	undefined
onTerminate	function	Callback when the request is over. It receives two objects as parameters (see below)	undefined
protocol	string	"auto" or "HTTP1". "auto" means HTTP1 in the current implementation	"auto"
proxyAuthentication	authentication object	object handling proxy authentication	undefined
serverAuthentication	authentication object	object handling server authentication	undefined
returnResponseBody	boolean	If false, the response body is not returned in the response object. Returns an error if false and onData is undefined	true
timeout	number	Timeout in seconds. Undefined = no timeout	undefined

Callback functions

All callback functions receive two object parameters:

Parameter	Type
param1	HTTPRequest object
param2	Event object

Here is the sequence of callback calls:

1. onHeaders is always called once
2. onData is called zero or several times (not called if the request does not have a body)
3. If no error occured, onResponse is always called once
4. If an error occurs, onError is executed once (and terminates the request)
5. onTerminate is always executed once

event object

An event object is returned when a callback function is called. It contains the following properties:

Property	Type	Description
.data	blob	Received data. It is always undefined except in the onData callback
.type	text	Type of event. Possible values: "response", "error", "headers", "data", or "terminate

authentication object

An authentication object handles the options.serverAuthentication or options.proxyAuthentication property. It can contain the following properties:

Property	Type	Description	Default
name	string	Name used for authentication	undefined
password	string	Password used for authentication	undefined
method	string	Method used for authentication: "basic", "digest", "auto"	"auto"

.dataType

dataType : string

Description

The .dataType property contains the dataType passed in the options object when calling new(), "auto" if it was omitted.

.encoding

encoding : string

Description

The .encoding property contains the encoding passed in the options object when calling new(), "UTF-8" if it was omitted.

.errors

errors : collection

Description

The .errors property contains the collection of all the errors if at least one error has been triggered.

Here is the contents of the .errors property:

Property		Type	Description
errors		collection	Qodly error stack in case of error
	[].errCode	Number	Qodly error code
	[].message	string	Description of the Qodly error
	[].componentSignature	string	Signature of the internal component which returned the error

.headers

headers : object

Description

The .headers property contains the headers passed in the options object when calling new(). If it was omitted, contains an empty object.

httpParseMessage

httpParseMessage( data : string ) : object
httpParseMessage( data : blob ) : object

Parameter	Type		Description
data	string, blob	→	Data to be parsed
Result	Object	←	Object, each property is a part of the multipart data

Description

The httpParseMessage command parses a multipart/form-data text or blob (HTTP "response" message) and extracts the content to an object. Each property of the returned object corresponds to a part of the multipart data.

info

HTTP itself is a stateless communication protocol. Within this framework, clients initiate communication by sending "request" messages to servers, specifying details like method, target, headers, content, etc. Servers, in turn, respond with "response" messages that include the same details. HTTP Parse message parses either the "request" or the "response" message into a well-organized object.

Example

var request : string=file("/SOURCES/Shared/HTTPrequest.txt").getText()
var parsedMessage : object=httpParseMessage(request)
//parsedMessage= {
//headers:{"User-Agent":"XX/20.4.0",...},
//parts:[{"contentType":"application/http","contentID":"item1",...}], 
//requestLine:"POST /batch/gmail/v1/ HTTP/1.1"
//}

.method

method : string

Description

The .method property contains the method passed in the options object when calling new(). If it was omitted, contains "GET".

.protocol

protocol : string

Description

The .protocol property contains the protocol passed in the options object when calling new(). If it was omitted or if "auto" was used, contains the version of the protocol used.

.response

response : object

Description

The .response property contains the response to the request if it has received at least the status code, undefined otherwise.

A response object is a non-sharable object. It provides the following properties:

Property	Type	Description
.body	variant	Body of the response. The type of the message is defined according to the dataType property. Undefined if the body has not been received yet
.headers	object	Headers of the response. Header names are returned in lowercase. <headername>.key = value (value can be a collection if the same key appears multiple times). Undefined if the headers have not been received yet.
.status	number	Status code of the response
.statusText	string	Message explaining the status code
.rawHeaders	object	Headers of the response. Header names are returned untouched (with their original case). <headerName>.key = value (value can be a collection if the same key appears multiple times). Undefined if the headers have not been received yet.

.returnResponseBody

returnResponseBody : boolean

Description

The .returnResponseBody property contains the returnResponseBody passed in the options object when calling new(). If it was omitted, contains true.

.terminate()

.terminate()

Parameter	Type		Description
			Does not require any parameters

Description

The .terminate() function aborts the HTTP request. It triggers the onTerminate event.

.terminated

terminated : boolean

Description

The .terminated property contains true if the request is terminated (after the call to onTerminate), false otherwise.

.timeout

timeout : number

Description

The .timeout property contains the timeout passed in the options object when calling new(). If it was omitted, contains undefined.

.url

url : string

Description

The .url property contains the URL of the HTTP request.

.wait()

.wait( { time : number } ) : HTTPRequestClass

Parameter	Type		Description
time	number	→	Maximum time in seconds to wait for the response
Result	4D.HTTPRequest	←	HTTPRequest object

Description

The wait() function waits for the response from the server.

If a time parameter is passed, the function will wait at most the defined number of seconds.

If the response from the server has already arrived, the function returns immediately.

note

During the .wait() execution, callback functions are executed, whether they originate from other instances of the same class, or instances of any classes supporting the same callback mechanism (HTTPRequest, TCPConnection, SystemWorker). You can exit from a .wait() by calling shutdown() or terminate() (depending on the API) from a callback.