HTTP Client Functions
The client functions are used to exchange data with a HTTP/HTTPS server. There are specific functions for GET and POST as well as functions for general HTTP requests. Either plain text or encrypted communication can be used. Basic authentication is supported, as well as the use of a keystore, and if required a truststore, for the functions with an encrypted communication channel.
The HTTP client functions also support the use of proxy, see HTTP Proxy Support for information on how to setup HTTP proxy support.
The following functions for HTTP Client described here are:
- 1 httpGetURL
- 2 httpBinaryGetURL
- 3 httpGetSecureURL
- 4 httpBinaryGetSecureURL
- 5 httpPostURL
- 6 httpBinaryPostURL
- 7 httpPostSecureURL
- 8 httpBinaryPostSecureURL
- 9 httpRequest
- 10 httpRequestBasicAuth
- 11 httpRequestSecureBasicAuth
- 12 httpRequestSecure
- 13 httpRequestDigestAuth
- 14 httpCreateMultipartBody
- 15 httpAddMultipartSegment
- 16 httpAddMultipartSegmentWithMapping
- 17 httpMultipartPostURL
- 18 httpMultipartPostSecureURL
- 19 TLS/SSL Encryption
httpGetURL
This function uses the GET method to retrieve content from an HTTP server.
string httpGetURL
( string query,
string host,
int timeout,
int port, //Optional
string username, //Optional
string password, //Optional
map<string, string> headers, //Optional
int connectTimeout) //Optional
Parameter | Description |
---|---|
| The query including path Example - query/api/v2/doc/1
/api/v2/doc?id=1 |
| The name or IP address where the HTTP server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The port number to contact the HTTP server on. Port 80 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | Content from the HTTP server. It will be |
httpBinaryGetURL
This function uses the GET method to retrieve binary content from an HTTP server.
bytearray httpBinaryGetURL
( string query,
string host,
int timeout,
int port, //Optional
string username, //Optional
string password, //Optional
map<string, string> headers, //Optional
int connectTimeout) //Optional
Parameter | Description |
---|---|
| The query including path Example - query |
| The name or IP address where the HTTP server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The port number to contact the HTTP server on. Port 80 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A bytearray from the HTTP server. It will be |
httpGetSecureURL
This function uses the GET method to retrieve content from an HTTPS server. The communication channel is encrypted.
Parameter | Description |
---|---|
| The query including path Example - query |
| The name or IP address where the HTTPS server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The port number to contact the HTTPS server on. Port 443 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | Content from the HTTPS server. It will be |
See the section below, TLS/SSL Encryption.
httpBinaryGetSecureURL
This function uses the GET method to retrieve binary content from an HTTPS server. The communication channel is encrypted.
Parameter | Description |
---|---|
| The query including path |
| The name or IP address where the HTTPS server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The port number to contact the HTTPS server on. Port 443 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A bytearray from the HTTPS server. It will be |
See the section below, TLS/SSL Encryption.
httpPostURL
This function uses the POST method to send content to an HTTP server and receives the response.
Parameter | Description |
---|---|
| The path |
| The MIME type of the content |
| The body of the request |
| The name or IP address where the HTTP server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The port number to contact the HTTP server on. Port 80 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | Content from the HTTP server. It will be |
httpBinaryPostURL
This function uses the POST method to send binary content to an HTTP server and receives the response.
Parameter | Description |
---|---|
| The path |
| The MIME type of the content |
| The body of the request |
| The name or IP address where the HTTP server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds. |
| The port number to contact the HTTP server on. Port 80 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A bytearray from the HTTP server. It will be |
httpPostSecureURL
This function uses the POST method to send content to an HTTPS server and receives the response. The communication channel is encrypted.
Parameter | Description |
---|---|
| The path |
| The MIME type of the content |
| The body of the request |
| The name or IP address where the HTTPS server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds. |
| The port number to contact the HTTPS server on. Port 443 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A document from the HTTP server. It will be |
See the section below, TLS/SSL Encryption.
httpBinaryPostSecureURL
This function uses the POST method to send binary content to an HTTP server and receives the response. The communication channel is encrypted.
Parameter | Description |
---|---|
| The path |
| The MIME type of the content |
| The body of the request |
| The name or IP address where the HTTPS server is running |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds. |
| The port number to contact the HTTPS server on. Port 443 is used by default. |
| A username for an account on the HTTP server |
| Password associated with the username |
| Custom HTTP request headers. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A bytearray from the HTTP server. It will be |
See the section below, TLS/SSL Encryption.
httpRequest
This function makes an HTTP request and uses the specified method, e g GET, POST, PUT etc.
Parameter | Description |
---|---|
| The HTTP method |
| The host and port of the HTTP server, e g http://host:port |
| Key-value pairs containing request header fields |
| The path |
| The body of the request. |
| The MIME type of the content |
dynamicArgs | The body of the request |
httpRequestBasicAuth
This function makes an HTTP request with basic authentication and uses the specified method, e g GET, POST, PUT etc.
Parameter | Description |
---|---|
| The HTTP method |
| The URL of the HTTP server |
| Key-value pairs containing request header fields |
| The MIME type of the content |
| The body of the request |
| The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout. |
| A username for an account on the HTTP server |
| Password associated with the username |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A response from the HTTP server. It will be |
httpRequestSecureBasicAuth
This function makes an HTTPS request with basic authentication and uses the specified method, e g GET, POST, PUT etc.
Parameter | Description |
---|---|
| The HTTP method |
| The URL of the HTTPS server |
| Key-value pairs containing request header fields |
| The MIME type of the content |
| The body of the request |
| The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout. |
| A username for an account on the HTTP server |
| Password associated with the username |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A response from the HTTPS server. It will be |
See the section below, TLS/SSL Encryption.
httpRequestSecure
This function makes an HTTPS request and uses the specified method, e g GET, POST, PUT etc.
Parameter | Description |
---|---|
| The method to be performed on the HTTPS server identified by the URL |
| The URL of the HTTPS server |
| Key-value pairs containing request header fields |
| The MIME type of the content |
| The body of the request |
| The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
Returns | A response from the HTTPS server. It will be |
See the section below, TLS/SSL Encryption.
httpRequestDigestAuth
This function sends a request to the server using Digest Authentication.
Parameter | Description |
---|---|
| The HTTP method |
| The URL of the HTTP server |
| Key-value pairs containing request header fields |
| The MIME type of the content |
| The body of the request |
| The username required for authentication |
| The password required for authentication |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The number of seconds to wait for a connection to be established. If the value is set to 0 (zero), the default timeout will be used. The default value is 15 seconds. |
| The name of the realm |
Returns | A response from the HTTP server. It will be null if any part of the communication fails. |
httpCreateMultipartBody
This function creates a multipart body that can be used in HTTP requests that accept a body.
Parameter | Description |
---|---|
Returns | A multipart body for HTTP requests to which typed binary segments can be added. |
httpAddMultipartSegment
This function adds a typed binary segment to a multipart body that has been created using httpAddMultipartBody
 function.
Parameter | Description |
---|---|
| A multipart body created by using the |
| The filename to be associated with the segment. |
| The MIME type of the content (according to RFC1341). |
| The binary content of the request. |
Returns | Nothing |
httpAddMultipartSegmentWithMapping
This function adds a typed binary segment to a multipart body that has been created using httpAddMultipartBody function and allows to specify a custom key name.
Parameter | Description |
---|---|
| A multipart body created by using the |
keyName | A custom key name that will be used for the fragment |
| The filename to be associated with the segment. |
| The MIME type of the content (according to RFC1341). |
| The binary content of the request. |
Returns | Nothing |
httpMultipartPostURL
This function uses the POST method to send multipart binary contents to an HTTP server and receives the response.
Parameter | Description |
---|---|
| The path on the server to which we should do the POST. |
| A multipart body created by using the |
| The name or IP address of the HTTPS server. |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds. |
| The port to be used for the HTTPS server. Port 80 is used by default. |
| Username for the account to be used on the HTTPS server. |
| Password for the account to be used on the HTTPS server. |
| Custom HTTP request headers. |
Returns | A bytearray from the HTTPS server. It will be null if any part of the communication fails. |
httpMultipartPostSecureURL
This function uses the POST method to send multipart binary content to an HTTPS server and receive the response.
Parameter | Description |
---|---|
| The path on the server to which we should do the POST. |
| A multipart body created by using the |
| The name or IP address of the HTTPS server. |
| The number of seconds to wait for a response. If the value is set to 0 (zero), the default timeout will be used. Default value is 15 seconds. |
| The port to be used for the HTTPS server. Port 80 is used by default. |
| Username for the account to be used on the HTTPS server. |
| Password for the account to be used on the HTTPS server. |
| Custom HTTP request headers. |
Returns | A bytearray from the HTTPS server. It will be null if any part of the communication fails. |
TLS/SSL Encryption
The following functions require a keystore in order to work, and if required, the use of a truststore is supported:
httpGetSecureURL
httpBinaryGetSecureURL
httpPostSecureURL
httpBinaryPostSecureURL
httpRequestSecureBasicAuth
httpRequestSecure
Configure Java Keystore for Secure URL Functions
Keystore is used to store HTTP Client’s credential. This certificate is sent to a server for authentication if required.
To specify a Keystore file that you want to use, set the properties https.apl.keystore_location
and https.apl.keystore_passphrase
in the relevant ECs. See the example below on how to set these properties using the mzsh topo
 command.
If the two properties above are not set in the relevant Execution Context <pico>.conf
, MZ Default Keystore is used.
The property  https.apl.keystore_location
  represents the location of the keystore and the property  https.apl.keystore_passphrase
  represents the passphrase for that keystore.
The following command can be used to create a keystore with the Java keytool program.
See the JVM product documentation for more information about how to use the keytool.
Configure Java Truststore for Secure URL FunctionsÂ
A truststore is a keystore that is used when deciding on what to trust - truststore stores certificates from third parties. If you receive data from an entity that you already trust, and if you can verify that the entity is that which it claims to be, you can assume that the data does in fact come from that entity.
By Default, uses its own truststore, which always trusts any server connection.
If you want to use a specific truststore, use the mzsh topo
command to add the property https.apl.userdefined.truststore
to the required ECs and set the value to true:
The default value of this property is false
.
After setting the property https.apl.userdefined.truststore
to true
, if you want to use a specific truststore, use the mzsh topo
command to set the following properties in the relevant ECs:
https.apl.truststore_location
https.apl.truststore_passphrase
If you do not set these two properties, the Java Default Truststore is used.