Versions Compared

Old Version 1

changes.mady.by.user Kevin Wu

Saved on

compared with

New Version Current

changes.mady.by.user Kevin Wu

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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:

Table of Contents
maxLevel1

httpGetURL

This function uses the GET method to retrieve content from an HTTP server.

Code Block
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

query

The query including path

Info

Example - query

Code Block
/api/v2/doc/1
/api/v2/doc?id=1

host

The name or IP address where the HTTP server is running

timeout

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.

port

The port number to contact the HTTP server on. Port 80 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

httpBinaryGetURL

This function uses the GET method to retrieve binary content from an HTTP server.

Code Block
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

query

The query including path

Info

Example - query

Code Block
/api/v2/img/1
/api/v2/img?id=1

host

The name or IP address where the HTTP server is running

timeout

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.

port

The port number to contact the HTTP server on. Port 80 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

httpGetSecureURL

This function uses the GET method to retrieve content from an HTTPS server. The communication channel is encrypted.

Code Block
string httpGetSecureURL
    ( 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

query

The query including path

Info

Example - query

Code Block
/api/v2/doc/1
/api/v2/doc?id=1

host

The name or IP address where the HTTPS server is running

timeout

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.

port

The port number to contact the HTTPS server on. Port 443 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

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.

Code Block
bytearray httpBinaryGetSecureURL
    ( 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

query

The query including path

Info

Example - query

Code Block
/api/v2/img/1
/api/v2/img?id=1

host

The name or IP address where the HTTPS server is running

timeout

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.

port

The port number to contact the HTTPS server on. Port 443 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

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.

Code Block
string httpPostURL
    ( string path,		
      string contentType,
      string content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter

Description

path

The path

Info

Example - path

Code Block
/api/v2/doc

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

content

The body of the request

host

The name or IP address where the HTTP server is running

timeout

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.

port

The port number to contact the HTTP server on. Port 80 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

httpBinaryPostURL

This function uses the POST method to send binary content to an HTTP server and receives the response.

Code Block
bytearray httpBinaryPostURL
    ( string path,		
      string contentType,
      bytearray content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter

Description

path

The path

Info

Example - path

Code Block
/api/v2/img

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/octet-stream

content

The body of the request

host

The name or IP address where the HTTP server is running

timeout

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.

port

The port number to contact the HTTP server on. Port 80 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

httpPostSecureURL

This function uses the POST method to send content to an HTTPS server and receives the response. The communication channel is encrypted.

Code Block
string httpPostSecureURL
    ( string path,		
      string contentType,
      string content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter

Description

path

The path

Info

Example - path

Code Block
/api/v2/doc

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

content

The body of the request

host

The name or IP address where the HTTPS server is running

timeout

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.

port

The port number to contact the HTTPS server on. Port 443 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

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.

Code Block
bytearray httpBinaryPostSecureURL
    ( string path,		
      string contentType,
      bytearray content,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers, //Optional
	  int connectTimeout)		   //Optional

Parameter

Description

path

The path

Info

Example - path

Code Block
/api/v2/img

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/octet-stream

content

The body of the request

host

The name or IP address where the HTTPS server is running

timeout

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.

port

The port number to contact the HTTPS server on. Port 443 is used by default.

username

A username for an account on the HTTP server

password

Password associated with the username

headers

Custom HTTP request headers.

connectTimeout

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 null if any part of the communication fails.

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.

Code Block
string httpRequest
    ( string method,		
      string url,
      string path,
      string content,
      string contentType,
      list dynamicArgs)	//Opt

Parameter

Description

method

The HTTP method

url

The host and port of the HTTP server, e g http://host:port

header

Key-value pairs containing request header fields

path

The path

Info

Example - path

Code Block
/api

content

The body of the request.

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

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.

Code Block
string httpRequestBasicAuth
    ( string method,		
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
      string username
      string password,
	  int connectTimeout)	//Optional

Parameter

Description

method

The HTTP method

url

The URL of the HTTP server

header

Key-value pairs containing request header fields

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

content

The body of the request

timeout

The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout.

username

A username for an account on the HTTP server

password

Password associated with the username

connectTimeout

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 null if any part of the communication fails.

httpRequestSecureBasicAuth

This function makes an HTTPS request with basic authentication and uses the specified method, e g GET, POST, PUT etc.

Code Block
string httpRequestSecureBasicAuth
    ( string method,		
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
      string username,
      string password,
	  int connectTimeout)	//Optional

Parameter

Description

method

The HTTP method

url

The URL of the HTTPS server

header

Key-value pairs containing request header fields

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

content

The body of the request

timeout

The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout.

username

A username for an account on the HTTP server

password

Password associated with the username

connectTimeout

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 null if any part of the communication fails.

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

Code Block
string httpRequestSecure
    ( string method,		
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
	  int connectTimeout)	//Optional

Parameter

Description

method

The method to be performed on the HTTPS server identified by the URL

url

The URL of the HTTPS server

header

Key-value pairs containing request header fields

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

content

The body of the request

timeout

The number of milliseconds to wait for a response. A timeout of 0 (zero) is interpreted as an infinite timeout.

connectTimeout

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 null if any part of the communication fails.

See the section below, TLS/SSL Encryption.

httpRequestDigestAuth

This function sends a request to the server using Digest Authentication.

Code Block
string httpRequestDigestAuth
    ( string method, 
      string url,
      map<string,string> header,
      string contentType,
      string content,
      int timeout,
      string username,
      string password,
      int connectTimeout, 			//Optional
      string realm) 				//Optional

Parameter

Description

method

The HTTP method

url

The URL of the HTTP server

header

Key-value pairs containing request header fields

contentType

The MIME type of the content

Info

Example - contentType

Code Block
/application/json

content

The body of the request

username

The username required for authentication

password

The password required for authentication

timeout

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.

connectTimeout

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.

realm

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.

Code Block
any httpCreateMultipartBody ( )

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.

Code Block
void httpAddMultipartSegment
    ( any body,
      string filename,
      string contentType,
      bytearray content )

Parameter

Description

body

A multipart body created by using the httpAddMultipartBody function.

filename

The filename to be associated with the segment.

contentType

The MIME type of the content (according to RFC1341).

content

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.

Code Block
void httpAddMultipartSegmentWithMapping
    ( any body,
      string keyName
      string filename,
      string contentType,
      bytearray content )

Parameter

Description

body

A multipart body created by using the httpAddMultipartBody function.

keyName

A custom key name that will be used for the fragment

filename

The filename to be associated with the segment.

contentType

The MIME type of the content (according to RFC1341).

content

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.

Code Block
bytearray httpMultipartPostURL
    ( string path,
      any body,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers) //Optional

Parameter

Description

path

The path on the server to which we should do the POST.

body

A multipart body created by using the httpCreateMultipartBody function and populated using the httpAddMultipartSegment function.

host

The name or IP address of the HTTPS server.

timeout

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.

port

The port to be used for the HTTPS server. Port 80 is used by default.

username

Username for the account to be used on the HTTPS server.

password

Password for the account to be used on the HTTPS server.

headers

Custom HTTP request headers.

Returns

A bytearray from the HTTPS server. It will be null if any part of the communication fails.

Note

Note!

For optional parameters, you need to state null in case you state subsequent optional parameters. If there are no subsequent parameters, you do not have to state anything.

Info
titleExample


Code Block
httpMultipartPostURL( "mypath", mybody, ""myhost, 0, null, "myusername");


httpMultipartPostSecureURL

This function uses the POST method to send multipart binary content to an HTTPS server and receive the response.

Code Block
bytearray httpMultipartPostSecureURL
    ( string path,
      any body,
      string host,
      int timeout,
      int port,                    //Optional
      string username,             //Optional
      string password,             //Optional
      map<string, string> headers) //Optional

Parameter

Description

path

The path on the server to which we should do the POST.

body

A multipart body created by using the httpCreateMultipartBody function and populated using the httpAddMultipartSegment function.

host

The name or IP address of the HTTPS server.

timeout

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.

port

The port to be used for the HTTPS server. Port 80 is used by default.

username

Username for the account to be used on the HTTPS server.

password

Password for the account to be used on the HTTPS server.

headers

Custom HTTP request headers.

Returns

A bytearray from the HTTPS server. It will be null if any part of the communication fails.

Note

Note!

For optional parameters, you need to state null in case you state subsequent optional parameters. If there are no subsequent parameters, you do not have to state anything.

Info
titleExample


Code Block
httpMultipartPostSecureURL( "mypath", mybody, ""myhost, 0, null, "myusername");


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

Anchor
JavaKeystore
JavaKeystore
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.

Info

Example - Setting Java keystore properties


Code Block
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.keystore_location <location of the Keystore file>
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.keystore_passphrase <DR encrypted password>


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.

Code Block
keytool -keystore /var/opt/mz/HttpdExec.keystore -genkey -keyalg RSA
Note

Note!

The Keystore passphrase must be the same as the passphrase used by the certificate.

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, Image Added 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:

Code Block
languagetext
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.userdefined.truststore 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

Info

Example - Setting properties to use a specific truststore
Code Block
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.truststore_location <location of the truststore file>
$ mzsh topo set topo://container:<container>/pico:<pico>/val:config.properties.https.apl.truststore_passphrase <DR encrypted password>

If you do not set these two properties, the Java Default Truststore is used.