Built-in HTTP Components
InterSystems IRIS® data platform provides built-in business hosts that use the HTTP adapters, allowing you to add HTTP support to a production without creating a custom business service or business operation. This page briefly introduces them, as well as the generic HTTP message class.
Available HTTP Business Hosts
If you need a business service that uses the HTTP inbound adapter, you can add EnsLib.HTTP.GenericServiceOpens in a new tab to the production. This business service uses EnsLib.HTTP.InboundAdapterOpens in a new tab as its adapter.
Similarly, a production that needs to leverage the HTTP outbound adapter can use EnsLib.HTTP.GenericOperationOpens in a new tab. This business operation uses EnsLib.HTTP.OutboundAdapterOpens in a new tab as its adapter.
Generic HTTP Message Class
InterSystems IRIS provides a message class designed to carry a HTTP request or response through a production. This message class, EnsLib.HTTP.GenericMessageOpens in a new tab, includes the headers and body of the HTTP request. In some cases, it may be useful to construct a EnsLib.HTTP.GenericMessageOpens in a new tab from scratch and then send it out using EnsLib.HTTP.GenericOperationOpens in a new tab. This process consists of building the body and populating the headers before creating the new message. The following is an example:
// Build the header
#dim tRESTHTTPHeaders
Set tRESTHTTPHeaders("HttpRequest")="POST"
Set tRESTHTTPHeaders("HTTPVersion")="1.1"
// Build the body
#dim tPOSTStream = ##class(%Stream.GlobalCharacter).%New()
#dim tPOSTJSON = {}
Set tPOSTJSON.projection = []
Do tPOSTJSON.projection.%Push("%Doc")
Do tPOSTJSON.%ToJSON(.tPOSTStream)
// Add more headers
Set tRESTHTTPHeaders("content-length") = tPOSTStream.Size
Set tRESTHTTPHeaders("content-type") = "application/json"
// Create message
Return ##class(EnsLib.HTTP.GenericMessage).%New(tPOSTStream,,.tRESTHTTPHeaders)
When creating the HTTP message using EnsLib.HTTP.GenericMessage.%New(), you have several options for passing in the headers. Commonly, the header argument is passed in as an array. However, the %New() method also accepts headers as an ObjectScript array reference, an %AbstractStreamOpens in a new tab with its own Attributes to copy from, an %Net.HttpResponseOpens in a new tab object with its own Headers to copy from, or a string of the form 'a=1,b=2,c=3'.
Target URL of the HTTP Request
When a production uses EnsLib.HTTP.GenericOperationOpens in a new tab, the URL header of the message is processed in conjunction with the URL property of the outbound adapter to determine the URL path of the request. Like other adapter properties, the value of this URL property is determined by the URL setting of the production’s business operation. For details on how the URL header and the URL property interact, refer to the class reference for the URL propertyOpens in a new tab of EnsLib.HTTP.OutboundAdapterOpens in a new tab.
URL Parameters
By default, URL parameters are sent in the HTTP request body. To force URL parameters to be sent in the URL, set the RawParams HTTP header. (If the IParams header is specified, then that will be used if the RawParams header is empty.)
More About Message Headers
The following example shows what the headers of a EnsLib.HTTP.GenericMessage might look like if it were created by InterSystems IRIS:
<HTTPHeaders>
<HTTPHeadersItem HTTPHeadersKey="CharEncoding" xsi:nil="true"></HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="EnsConfigName">ForDocker</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="HTTPVersion">1.1</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="HttpRequest">POST</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="IParams">0</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="RawParams" xsi:nil="true"></HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="TranslationTable">RAW</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="URL">/api/atelier/v4/TEST/action/query</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="accept">application/json, text/plain, */*</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="connection">close</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="content-length">127</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="content-type">application/json</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="cookie">CSPSESSIONID-SP-42773-UP-api-atelier-=001000000000t7LT7VX9SXUNIM7S8yKxK44S$uBbUtzNHVjIAk</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="host">127.0.0.1:55773</HTTPHeadersItem>
<HTTPHeadersItem HTTPHeadersKey="user-agent">axios/0.21.1</HTTPHeadersItem>
</HTTPHeaders>
If you are building a EnsLib.HTTP.GenericMessageOpens in a new tab from scratch, not all of these headers are required. At a minimum, the HttpRequest, HTTPVersion, and content-type headers should be defined, and the content-length header is also commonly defined.
