Specifying Other HTTP Request Properties

The Location Property

The Location property specifies the resource that you are requesting from the web server. If you set this property, then when you call the Get(), Head(), Post(), or Put() method, you can omit the location argument.

For example, suppose that you are sending an HTTP request to the URL http://machine_name/test/index.html

In this case, you would use the following values:

Specifying the Internet Media Type and Character Encoding

You can use the following properties to specify the Internet media typeOpens in a new tab (also called MIME type) and character encoding in your instance of %Net.HttpRequestOpens in a new tab and its response:

• ContentType specifies the Content-Type header, which specifies the Internet media type of the request body. The default type is none.

  Possible values include application/json, application/pdf, application/postscript, image/jpeg, image/png, multipart/form-data, text/html, text/plain, text/xml, and many others. For an extensive list, see http://www.iana.org/assignments/media-typesOpens in a new tab.

• The ContentCharset property controls the desired character set for any content of the request if the content is of type text (text/html or text/xml for example). If you do not specify this property, InterSystems IRIS uses the default encoding of the InterSystems IRIS server.

  Note:

  If you set this property, you must first set the ContentType property.

• The NoDefaultContentCharset property controls whether to include an explicit character set for content of type text if you have not set the ContentCharset property. By default, this property is false.

  If this property is true, then if you have content of type text and if you have not set the ContentCharset property, no character set is included in the content type; this means that the character set iso-8859–1 is used for the output of the message.

• The WriteRawMode property affects the entity body (if included). It controls how the body of the request is written. By default, this property is false and InterSystems IRIS writes the body in the encoding that is specified in the request headers. If this property is true, InterSystems IRIS writes the body in RAW mode (performing no translation of the character set).

• The ReadRawMode property controls how the body of the response is read. By default, this property is false and InterSystems IRIS assumes that the body is in the character set specified in the response headers. If this property is true, InterSystems IRIS reads the body in RAW mode (performing no translation of the character set).

Using a Proxy Server

You can send an HTTP request via a proxy server. In order to set this up, specify the following properties of your HTTP request:

• ProxyServer specifies the host name of the proxy server to use. If this property is not null, the HTTP request is directed to this machine.

• ProxyPort specifies the port to connect to, on the proxy server.

• ProxyAuthorization specifies the Proxy-Authorization header, which you must set if a user agent must authenticate itself with a proxy. For the value, use the authentication information required by the user agent for the resource that you are requesting. Also see Providing Login Credentials.

• ProxyHTTPS controls whether the HTTP request is for an HTTPS page, rather than a normal HTTP page. This property is ignored if you have not specified a proxy server. This property changes the default port on the target system to 443, the proxy port. Also see Using SSL to Connect.

• ProxyTunnel specifies whether to establish a tunnel through the proxy to the target HTTP server. If true, the request uses the HTTP CONNECT command to establish a tunnel. The address of the proxy server is taken from the ProxyServer and ProxyPort properties. If ProxyHttps is true, then once the tunnel is established, InterSystems IRIS negotiates the SSL connection. In this case, the Https property is ignored because the tunnel establishes a direct connection with the target system.

For details, see the class documentation for %Net.HttpRequestOpens in a new tab.

Using SSL to Connect

The %Net.HttpRequestOpens in a new tab class supports SSL connections. To send the request via SSL, do the following:

1. Set the SSLConfiguration property to the name of the activated SSL/TLS configuration to use.

   For information on creating and managing SSL/TLS configurations, see InterSystems TCP Guide. The SSL/TLS configuration includes an option called Configuration Name, which is the string to use in this setting.

2. Also do one of the following, depending on whether you are using a proxy server:

   • If you are not using a proxy server, set the Https property to true.

   • If you are using a proxy server, set the ProxyHTTPS property to true.

     In this case, to use an SSL connection to the proxy server itself, set the Https property to true.

Note that when you use an SSL connection to a given server, the default port on that server is assumed to be 443 (the HTTPS port). For example, if you are not using a proxy server and Https is true, this changes the default Port property to 443.

Also see Using a Proxy Server.

The HTTPVersion, Timeout, WriteTimeout, and FollowRedirect Properties

%Net.HttpRequestOpens in a new tab also provides the following properties:

• HTTPVersion specifies the HTTP version to use when requesting a page. The default is "HTTP/1.1". You can also use the "HTTP/1.0".

• Timeout specifies how long, in seconds, to wait for a response from the web server. The default is 30 seconds.

• WriteTimeout specifies how long, in seconds, to wait for a write the web server to complete. By default it will wait indefinitely. The minimum accepted value is 2 seconds.

• FollowRedirect specifies whether to automatically follow redirection requests from the web server (signalled by the HTTP status codes in the range 300–399). The default is true if you are using GET or HEAD; otherwise it is false.

Specifying Default Values for HTTP Requests

You can specify default values for all properties of %Net.HttpRequestOpens in a new tab.

• To specify a default value that apply to all namespaces, set the global node ^%SYS("HttpRequest","propname") where "propname" is the name of the property.

• To specify a default value for one namespace, go to that namespace and set the node ^SYS("HttpRequest","propname")

  (The ^%SYS global affects the entire installation, and the ^SYS global affects the current namespace.)

For example to specify a default proxy server for all namespaces, set the global node ^%SYS("HttpRequest","ProxyServer")