Sending HTTP Requests

Copy link to this sectionAuthenticating a Request When Using HTTP 1.0

For HTTP 1.0, to authenticate an HTTP request, set the Username and Password properties of the instance of %Net.HttpRequest. The instance then creates the HTTP Authorization header based on that username and password, using the Basic Access Authentication (RFC 2617). Any subsequent request sent by this %Net.HttpRequest will include this header.

Copy link to this sectionAuthenticating a Request When Using HTTP 1.1

For HTTP 1.1, to authenticate an HTTP request, in most cases, just set the Username and Password properties of the instance of %Net.HttpRequest. When an instance of %Net.HttpRequest receives a 401 HTTP status code and WWW-Authenticate header, it attempts to respond with an Authorization header that contains a supported authentication scheme. The first scheme that is supported and configured for InterSystems IRIS is used. By default, it considers these authentication schemes, in order:

1. Negotiate (SPNEGO and Kerberos, per RFC 4559 and RFC 4178)

2. NTLM (NT LAN Manager Authentication Protocol)

3. Basic (Basic Access Authentication as described in RFC 2617)

   Important:

   If there is a chance that Basic authentication will be used, make sure to also use SSL (see “Using SSL to Connect”). In Basic authentication, the credentials are sent in base-64 encoded form and thus can be easily read.

On Windows, if the Username property is not specified, InterSystems IRIS can instead use the current login context. Specifically, if the server responds with a 401 status code and a WWW-Authenticate header for SPNEGO, Kerberos, or NTLM, then InterSystems IRIS uses the current operating system username and password to create the Authorization header.

The details are different from the HTTP 1.0 case, as follows:

• If authentication succeeds, InterSystems IRIS updates the CurrentAuthenticationScheme property of the %Net.HttpRequest instance to indicate the authentication scheme that it used for the most recent authentication.

• If an attempt to get an authentication handle or token for a scheme fails, InterSystems IRIS saves the underlying error to the AuthenticationErrors property of the %Net.HttpRequest instance. The value of this property is a $LIST, in which each item has the form scheme ERROR: message

Negotiate and NTLM are supported only for HTTP 1.1 because these schemes require multiple round trips, and HTTP 1.0 requires the connection to be closed after each request/response pair.

Copy link to this sectionSpecifying the Authorization Header Directly

For either HTTP 1.0 or HTTP 1.1 (if applicable to your scenario), you can specify the HTTP Authorization header directly. Specifically, you set the Authorization property equal to the authentication information required by the user agent for the resource that you are requesting.

If you specify the Authorization property, the Username and Password properties are ignored.

Copy link to this sectionEnabling Logging for HTTP Authentication

To enable logging for the HTTP authentication, enter the following in the Terminal:

 set $namespace="%SYS"
 kill ^ISCLOG
 set ^%ISCLOG=2
 set ^%ISCLOG("Category","HttpRequest")=5

Copy code to clipboard

Log entries are written to the ^ISCLOG global. To write the log to a file (for easier readability), enter the following (still within the %SYS namespace):

 do ##class(%OAuth2.Utils).DisplayLog("filename")

Copy code to clipboard

Where filename is the name of the file to create. The directory must already exist. If the file already exists, it is overwritten.

To stop logging, enter the following (still within the %SYS namespace):

 set ^%ISCLOG=0
 set ^%ISCLOG("Category","HttpRequest")=0

Copy code to clipboard

Copy link to this sectionThe 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:

Copy link to this sectionSpecifying the Internet Media Type and Character Encoding

You can use the following properties to specify the Internet media type (also called MIME type) and character encoding in your instance of %Net.HttpRequest 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-types.

• 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).

Copy link to this sectionUsing 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.HttpRequest.

Copy link to this sectionUsing SSL to Connect

The %Net.HttpRequest 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.”

Copy link to this sectionThe HTTPVersion, Timeout, WriteTimeout, and FollowRedirect Properties

%Net.HttpRequest 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.

Copy link to this sectionSpecifying Default Values for HTTP Requests

You can specify default values for all properties of %Net.HttpRequest.

• 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")

Copy link to this sectionSending a Chunked Request

If you use HTTP 1.1, you can send an HTTP request in chunks. This involves setting the Transfer-Encoding to indicate that the message is chunked, and using a zero-sized chunk to indicate completion.

Chunked encoding is useful when the server is returning a large amount of data and the total size of the response is not known until the request is fully processed. In such a case, you would normally need to buffer the entire message until the content length could be computed (which %Net.HttpRequest does automatically).

To send a chunked request, do the following:

1. Create a subclass of %Net.ChunkedWriter, which is an abstract stream class that defines an interface for writing data in chunks.

   In this subclass, implement the OutputStream() method.

2. In your instance of %Net.HttpRequest, create an instance of your %Net.ChunkedWriter subclass and populate it with the request data that you want to send.

3. Set the EntityBody property of your %Net.HttpRequest instance equal to this instance of %Net.ChunkedWriter.

   When you send the HTTP request (see “Sending the HTTP Request”), it calls the OutputStream() method of the EntityBody property.

In your subclass of %Net.ChunkedWriter, the OutputStream() method should examine the stream data, decide whether to chunk it and how to do so, and invoke the inherited methods of the class to write the output.

The following methods are available:

If non-null, the TranslateTable property specifies the translation table to use to translate each string as it is written. All of the preceding methods check this property.

Copy link to this sectionExample 1

After inserting the form data, you generally call the Post() method. For example:

    Do httprequest.InsertFormData("element","value")
    Do httprequest.Post("/cgi-bin/script.CGI")

Copy code to clipboard

Copy link to this sectionExample 2

For another example:

    Set httprequest=##class(%Net.HttpRequest).%New()
    set httprequest.SSLConfiguration="MySSLConfiguration"
    set httprequest.Https=1
    set httprequest.Server="myserver.com"
    set httprequest.Port=443
    Do httprequest.InsertFormData("portalid","2000000")
    set tSc = httprequest.Post("/url-path/")
    Quit httprequest.HttpResponse

Copy code to clipboard

Copy link to this sectionAccessing the Data of the Response

The body of the HTTP response is contained in the Data property of the response. This property contains a stream object (specifically %GlobalBinaryStream). To work with this stream, use the standard stream methods: Write(), WriteLine(), Read(), ReadLine(), Rewind(), MoveToEnd(), and Clear(). You can also use the Size property of the stream.

The ReadRawMode property of the request 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 HTTP headers of the response (and translates the character set accordingly).

• If this property is true, InterSystems IRIS reads the body in RAW mode (performing no translation of the character set).

You can also use the OutputToDevice() method, which writes the full response to the current device. The headers are not in the same order as generated by the web server.

The following shows a simple example in which we copy the response stream to a file and save it:

 set request=##class(%Net.HttpRequest).%New()
 set request.Server="tools.ietf.org"
 set request.Https=1
 set request.SSLConfiguration="TEST"
 set status=request.Get("/html/rfc7158")
 if $$$ISERR(status) {
         do $system.OBJ.DisplayError()
 } else {
         set response=request.HttpResponse
 }
 
 Set file=##class(%FileCharacterStream).%New()
 set file.Filename="c:/temp/rfc7158.html"
 set status=file.CopyFrom(response.Data)
 if $$$ISERR(status) {
         do $system.OBJ.DisplayError()
 }
 do file.%Close()

Copy code to clipboard

Copy link to this sectionGetting an HTTP Header by Name

The %Net.HttpResponse class stores its HTTP headers in an InterSystems IRIS multidimensional array. To access the headers, use the following methods:

Each of these methods takes a single argument, a string that is the name of an HTTP header.

You can also use the OutputHeaders() method, which writes the HTTP headers to the current device (although not in the same order they were generated).

Copy link to this sectionAccessing Other Information about the Response

The %Net.HttpResponse class provides properties that store other specific parts of the HTTP response:

• StatusLine stores the HTTP status line, which is the first line of the response.

• StatusCode stores the HTTP status code.

• ReasonPhrase stores the human-readable reason that corresponds to StatusCode.

• ContentInfo stores additional information about the response body.

• ContentType stores the value of the Content-Type: header.

• HttpVersion indicates the version of HTTP that is supported by the web server that sent the response.