Chapter 1 Sending HTTP Requests

This topic describes how to send HTTP requests (such as POST or GET) and process responses.

Introduction to HTTP Requests

You can create instances of % net.Httprequest to send various HTTP requests and receive responses. This object acts as a Web browser and can be used to make multiple requests. It automatically sends the correct cookie and sets the Referer header as needed.

To create an HTTP request, use the following general process:

  1. create%Net.HttpRequestThe instance.
  2. Set the properties of this instance to indicate the Web server to communicate with. The basic attributes are as follows:
  • Server Specifies the IP address or computer name of the Web server. The default value islocalhost.

Note: Do not takehttp：//orhttps：//As part of the server value. This will lead to errors#6059: Cannot open TCP/IP socket to server HTTP: /.

  1. You can optionally set additional properties of the HTTP request and invoke methods, as described in Specifying Additional HTTP request properties.
  2. Then, by calling%Net.HttpRequestThe instanceget()Method or another method to send an HTTP request, as described in “Send AN HTTP Request.”

Multiple requests can be made from the instance, which automatically handles the cookie and Referer headers.

Note: If this HTTP request was created to be used with the production Outbound Adapter (enslib.http.outbound Adapter), send the request in the Adapter’s way instead.

  1. Use if needed%Net.HttpRequestSends other HTTP requests to the same instance of. By default, InterSystems IRIS leaves TCP/IP sockets open so that the socket can be reused without having to close and reopen it.

Here is a simple example:

/// w ##class(PHA.TEST.HTTP).Get()
ClassMethod Get(a)
{
	set request=##class(%Net.HttpRequest%).New(a)set request.Server="tools.ietf.org"
	set request.Https=1
	set request.SSLConfiguration="yx"
	set status=request.Get("/html/rfc7158")
	d $System.Status.DisplayError(status) 

	s response = request.HttpResponse
	s stream = response.Data
	q stream.Read()
}

Copy the code

Provide authentication

If the target server requires login credentials, the HTTP request can include HTTP Authorization headers that provide the credentials.

If you are using a proxy server, you can also specify the proxy server login credentials. To do this, set the ProxyAuthorization attribute

Authenticate requests when using HTTP 1.0

For HTTP 1.0, to validate HTTP requests, set the username and password properties for the % net.Httprequest instance. The example then uses basic access authentication to create an HTTP Authorization header (RFC 2617) based on the user name and password. Any subsequent requests sent by this % net.Httprequest will include this header.

Important: Make sure SSL is also used. In basic authentication, credentials are sent in base-64 encoding and therefore easy to read.

Authenticate requests when using HTTP 1.1

For HTTP 1.1, to validate HTTP requests, in most cases, you simply set the username and password attributes of the % net.Httprequest instance. When an instance of % net.Httprequest receives the 401 HTTP status code and www-Authenticate header, it attempts to respond with the Authorization header containing the supported authentication scheme. Use the first scenario supported and configured for IRIS. By default, it considers these authentication schemes in the following order:

  1. Negotiation (SPNEGO and Kerberos, according to RFC 4559 and RFC 4178)
  2. NTLM(NT LAN Manager Authentication Protocol)
  3. Basic authentication (Basic access authentication described in RFC 2617)

Important: If basic authentication is possible, make sure SSL is also used (see “Connect with SSL”). In basic authentication, credentials are sent in base-64 encoding, so they are easy to read.

On Windows, IRIS can use the current login context if the Username property is not specified. Specifically, if the server responds with a 401 status code and www-Authenticate header for SPNEGO, Kerberos, or NTLM, IRIS creates the Authorization header using the current operating system username and password.

This differs from HTTP 1.0, as follows:

  1. If the certification is successful, IRIS will be updated%NettheCurrentAuthenticationSchemeProperties.

HttpRequest instance to indicate the authentication scheme it used in the most recent authentication. 2. If attempts to get the authentication handle or token for the scheme fail, IRIS saves the underlying error to the AuthenticationErrors property of the % net.Httprequest instance. The value of this property is $List, each of which has the format Scheme ERROR: message

Only HTTP 1.1 supports negotiation and NTLM, as these scenarios require multiple round trips, while HTTP 1.0 requires the connection to be closed after each request/response pair.

Variations

If you know one or more authentication schemes allowed by the server, you can bypass the initial round trip of the server by including the Authorization header, which contains the initial token of the server for the selected scheme. To do this, set the InitiateAuthentication attribute of the % net.Httprequest instance. For the value of this property, specify the name of a single authorization scheme that the server allows. Use one of the following values (case sensitive) :

  • Negotiate
  • NTLM
  • Basic

If you want to customize the AuthenticationSchemes to use (or change the order in which they are considered), set AuthenticationSchemes for % net.httprequest instances. For the value of this property, specify a comma-separated list of authentication scheme names (using the exact value given in the previous list).

Specify the authorization header directly

For HTTP 1.0 or HTTP 1.1, if applicable, you can specify the HTTP Authorization header directly. Specifically, the Authorization attribute can be set to the authentication information required by the user agent equal to the resource being requested.

If the Authorization attribute is specified, the user name and password attributes are ignored.

Enable logging for HTTP authentication

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

 set $namespace="%SYS"
 kill ^ISCLOG
 set ^%ISCLOG=2
 set ^%ISCLOG("Category"."HttpRequest") =5
Copy the code

The log entry will be written to ^ISCLOG Global. To write the log to a file (for readability), enter the following (still in the %SYS namespace) :

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

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

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

 set ^%ISCLOG=0
 set ^%ISCLOG("Category"."HttpRequest") =0
Copy the code

Specify additional HTTP request attributes

Before sending an HTTP request (see Sending an HTTP Request), you can specify its properties, as described in the following sections:

You can specify default values for all attributes of % net.Httprequest, as specified in the last section listed.

The Location attribute

The Location property specifies the resource requested from the Web server. If this property is set, the location argument can be omitted when calling Get(), Head(), Post(), or Put() methods.

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

In this case, the following values will be used:

Sample properties for % net.Httprequest

Properties Value
Server machine_name
Location test/index.html

Specify Internet Media Type and Character Encoding

You can specify the Internet media type (also known as MIME type) and character encoding in the % net.Httprequest instance and its response using the following properties:

  • The content-type specifiesContent-TypeHeader that specifies the Internet media type for 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, and text/pl An, text/ XML, and so on

  • The ContentCharset property controls any content requested (for example,text/htmlortext/xml) character set required when type. If this property is not specified, InterSystems IRIS will use the default encoding of the InterSystems IRIS server.

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

  • NoDefaultContentCharsetProperty control is not setContentCharsetProperty in the case of whether to include text-type content in an explicit character set. By default, this property is False.

If this property is true, then no character set is included in the content type if there is text-type content and the ContentCharset property is not set. This means that the character set ISO-8859-1 is used for message output.

  • The WriteRawMode property affects the body of the entity, if included. It controls how the body of the request is written. By default, this property is False, and InterSystems IRIS writes the body with the encoding specified in the request header. If this property is true, InterSystems IRIS writes the body in raw mode (no character set conversion is performed).
  • ReadRawModeProperty controls how the response body is read. By default, this property is False, and InterSystems IRIS assumes that the body is in the character set specified in the response header. If this property is true, InterSystems IRIS reads the body in raw mode (no character set conversion is performed).

Using a proxy server

HTTP requests can be sent through a proxy server. To set this setting, specify the following properties for the HTTP request:

  • ProxyServerSpecify the host name of the proxy server to use. If this property is not empty, the HTTP request is directed to this computer.
  • ProxyPortSpecifies the port to connect to on the proxy server.
  • ProxyAuthorizationThe specifiedProxy-AuthorizationHeader that must be set if the user agent must authenticate itself with the agent. For this value, use the authentication information required by the user agent for the resource being requested.
  • ProxyHTTPSControls whether HTTP requests are for HTTPS pages or plain HTTP pages. If no proxy server is specified, this property is ignored. This property changes the default port on the target system to proxy port 443.
  • ProxyTunesSpecifies whether a tunnel to the target HTTP server is established through a proxy. If true, the request is made to establish a tunnel using the HTTP CONNECT command. The proxy server address is taken fromProxyServerandProxyPortProperties. ifProxyHttpsIf the value is true, IRIS will negotiate SSL connections between systems after the tunnel is established. In this case, the HTTPS attribute is ignored because the tunnel is directly connected to the target system.

Use SSL for connection

The % net.Httprequest class supports SSL connections. To send a request over SSL, do the following:

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

  2. Depending on whether a proxy server is used, you also need to do one of the following:

  • If the proxy server is not used, send thehttpsProperty set to true.
  • If a proxy server is used, set theProxyHTTPSProperty set to true.

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

Note that when using an SSL connection to a given server, the default port on that server is assumed to be 443(HTTPS port). For example, if a proxy server is not used and HTTPS is true, the Default Port property is changed to 443.

Server Identity Check

By default, when the % net.Httprequest instance connects to an SSL/TLS secure Web server, it checks to see if the certificate server name matches the DNS name used to connect to the server. If these names do not match, the connection is not allowed. This default behavior, which protects against man-in-the-middle attacks, is described in section 3.1 of RFC 2818; See also section 2.4 of RFC 2595.

To disable this check, use theSSLCheckServerIdentityProperty set to 0.

HTTPVersion,Timeout,WriteTimeoutandFollowRedirectattribute

% net.httprequest also provides the following properties:

HTTPVersion Specifies the HTTP version to use when requesting the page. The default is “HTTP/1.1”. You can also use “HTTP/1.0”.

Timeout Specifies the time, in seconds, to wait for a Response from the Web server. By default, it is 30 seconds.

WriteTimeout Specifies the time, in seconds, to wait for the Web server to finish writing. By default, it will wait indefinitely. The minimum acceptable value is 2 seconds.

FollowRedirect specifies whether redirected requests from the Web server are automatically tracked (signaled by HTTP status codes in the 300-399 range). If GET or HEAD is used, the default value is TRUE; Otherwise, it is FALSE.

Specify the default value for the HTTP request

You can specify default values for all attributes of % net.Httprequest.

  • To specify a default value for all namespaces, set the global section^%SYS("HttpRequest","propname"), including"PropName"Is the name of the property.
  • To specify a default value for a namespace, go to that namespace and set the node^SYS("HttpRequest","propname")

(^%SYS global Settings affect the entire installation, and ^SYS global Settings affect the current namespace.)

For example, to specify a default ProxyServer for all namespaces, set the global section ^%SYS(“HttpRequest”,”ProxyServer”)