# HTTP Proxy Server Configuration REST API

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:

| Property               | Description |
|-----------------------|-------------|
| `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. |
| `passwordIsIncluded`   | Always _false_ for the GET operation. |
| `excludeHosts`        | A list of hosts that are to be excluded from using the HTTP proxy server.<br>Each host value should conform to the standard values one would use for the [Java system property http.nonProxyHosts](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html).<br>The patterns may start or end with a '\*' for wildcards. Any host matching one of these patterns will be reached through a direct connection instead of through the proxy. |

## 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.