HTTP Proxy Server Configuration REST API - v2

NEW IN RELEASE 84

For IQ Server to be able to connect to other servers via an HTTP proxy server. The REST API described here allows system administrators to manage the HTTP proxy server configuration:

Query Current HTTP Proxy Server Configuration

To inspect the currently configured HTTP proxy server, you can make a request to the following path:

GET /api/v2/config/httpProxyServer

Below is an example request to a local IQ Server using the built-in administrator account and the cURL tool:

curl -u admin:admin123 http://localhost:8070/api/v2/config/httpProxyServer

If no HTTP proxy server is configured, the request yields HTTP status code 404. Otherwise, a JSON document with the following properties is returned:

PropertyDescription

hostname

The hostname or IP address of the HTTP proxy server to use for outgoing HTTP connections.

port

The port number for the HTTP proxy server.

username

The username needed to authenticate to the HTTP proxy server.

password

The password is always null (never included in the response) for the GET operation.

passwordIsIncludedAlways false for the GET operation.

excludeHosts

A list of hosts that are excluded.

Configure HTTP Proxy Server

To enable or update the HTTP proxy server, a PUT request to the aforementioned REST path is used:

PUT /api/v2/config/httpProxyServer

The request requires a JSON document as payload, using the same properties as already described above. The properties hostname and port are required.

If the password is specified in the input data, then passwordIsIncluded must be set to true. If passwordIsIncluded is set to true and the password is not included, then the password is null, which means "no password".

For update operations, if the password should remain unchanged, then the password can be omitted and passwordIsIncluded set to false. However, this is allowed only when the hostname and port are not changed. If the hostname or port is changed, then the password must be included and passwordIsIncluded must be set to true. The passwordIsIncluded flag is only used for update operations and it is not part of the HTTP proxy server configuration itself.

The next example demonstrates such a request:

curl -u admin:admin123 -H "Content-Type: application/json" -X PUT -d '{"hostname": "myproxyserver", "port": 8080, "username": "MyUsername", "password": "MySecret", "passwordIsIncluded": true, "excludeHosts": ["example.com", "example.org"]}' http://localhost:8070/api/v2/config/httpProxyServer

A successful update of the configuration is signaled by HTTP status code 204. If any required JSON property is missing or otherwise invalid, HTTP status code 400 is returned.

Disable HTTP Proxy Server

If IQ Server does not need an HTTP proxy server, the proxy server configuration can be entirely removed using the request:

DELETE /api/v2/config/httpProxyServer

For example:

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/config/httpProxyServer

If an HTTP proxy server was configured, the request responds with HTTP status code 204. If no HTTP proxy server was configured to begin with, the HTTP status code 404 is returned instead.