About this task
You might find it useful to read this information with
the Web services scenarios section.
You must decide which listener you want the HTTP
nodes to use:
- The integration node listener (the httplistener component) has
an HTTPConnector for handling HTTP messages, and an HTTPSConnector
for handling HTTPS (HTTP over SSL) messages. Each connector has its
own assigned port.
By default, all HTTPInput and HTTPReply nodes use the integration
node listener, which interfaces with the HTTP nodes by using a WebSphere® MQ queue.
The integration
node listener requires access to system queues on the queue manager
specified on the integration node, so you must install WebSphere MQ Server if you want to use an
integration node listener.
- An embedded listener is part of each integration server. The embedded
listener has an HTTPConnector and an HTTPSConnector, and each connector
has its own assigned port.
You can configure one or more integration
servers so that all HTTPInput and HTTPReply that you deploy to
that integration server use the embedded listener.
The
integration server embedded listener does not require access to WebSphere MQ.
For a discussion of the advantages of each listener, see
HTTP listeners.
You can use ProxyConnectHeaders only
with HTTPS (SSL) connections; these headers do not work with HTTP
connections.
- Using secure connections with HTTPS
- For information about setting up HTTPS connections, see Implementing SSL authentication.
- Using HTTP asynchronous request-response
- To make an HTTP request and receive a response asynchronously,
use the HTTPAsyncRequest and HTTPAsyncResponse nodes in
your message flow. The HTTPAsyncRequest node processes
the next message without waiting for the response, which is received
by the HTTPAsyncResponse node
on a different thread and in a new transaction. This means that many
more requests can be processed using fewer threads.
For more information,
see Using HTTP asynchronous request-response.
- Setting the HTTP Status Code for a reply
- The default HTTP Status Code is 200, which indicates success.
If you want a different status code to be returned, take one of the
following actions:
- Set your status code in the field Destination.HTTP.ReplyStatusCode
in the local environment tree (correlation name OutputLocalEnvironment).
This field overrides any status code that is set in an HTTPResponseHeader
header. This action is the preferred option, because it provides the
greatest flexibility.
- Set your status code in the field X-Original-HTTP-Status-Code
in the HTTPReplyHeader header.
- Set your status code in the field X-Original-HTTP-Status-Code
in the HTTPResponseHeader header. This option is useful if you include
an HTTPRequest node before
the HTTPReply node in your
flow, because the HTTPResponseHeader header is created for you. In
this scenario, an HTTPResponseHeader header has been created in the
logical tree, representing the HTTP headers in the response from another
web service. If you have selected the Generate
default HTTP headers from reply or response property on the HTTPReply node, values for
the response header are set as default values when the reply message
is created.
- Using LocalEnvironment.Destination.HTTP.RequestIdentifier
- When the HTTPInput node
receives an input request message, it sets the local environment field
Destination.HTTP.RequestIdentifier to a unique value that identifies
the web service client that sent the request. You can refer to this
value, and you can save it to another location if appropriate.
For
example, if you design a pair of message flows that interact with
an existing WebSphere MQ application
(as described in Integration node calls existing web service), you can save
the identifier value in the request flow, and restore it in the reply
flow, to ensure that the correct client receives the reply. If you
use this technique, you must not change the data, and you must retain
the data as a BLOB.
The HTTPReply node extracts the
identifier value from the local environment tree and sets up the reply
so that it is sent to the specific client. However, if
you are using an HTTPReply node
in a flow that does not have an HTTPInput node, and this field
has been deleted or set incorrectly, message BIP3143S is
issued.
If you design a message flow that includes both
an HTTPInput and an HTTPReply node, the identifier
value is set into the local environment by the HTTPInput node, but the HTTPReply node does not use
it. Therefore, if your message flow includes both HTTP nodes and a Compute node in the same flow,
you do not have to include the local environment tree when you specify
which components of the message tree are copied from input message
to output message by the Compute node
(the Compute mode property).
- Setting the HTTP request URL dynamically
- You can set the property Default
web service URL on the HTTPRequest or HTTPAsyncRequest node
to determine the destination URL for a web service request. You can
configure a Compute node
before the HTTPRequest or HTTPAsyncRequest node
within the message flow to override the value set in the property.
Code ESQL that stores a URL string in LocalEnvironment.Destination.HTTP.RequestURL;
the node retrieves and uses the URL string in place of the node property
value.
Although you can also set the request URL in the special
header X-Original-HTTP-URL in the HTTPRequestHeader header section
of the request message (which overrides all other settings) in a Compute node, use the local
environment tree content for this purpose for greater flexibility.
- Setting Generate default HTTP
headers from reply or response for the HTTPReply node
- If you select Generate default
HTTP headers from reply or response in the HTTPReply node properties,
the node includes a minimum set of headers in the response that
is sent to the web service client.
To
set headers explicitly, create them in an HTTPReplyHeader header.
For example, a
Compute node
propagates a message in the XMLNSC domain and modifies the
Content-Type as follows:
CALL CopyMessageHeaders();
SET OutputRoot.HTTPReplyHeader."Content-Type" = 'text/xml';
SET OutputRoot.XMLNSC = InputRoot.XMLNSC;
Do not
use the ContentType property to set the Content-Type unless you are
working in the MIME domain. The ContentType property is intended
to set the value of Content-Type used in MIME.
The full
set of HTTP headers used in the reply is built by selecting
the headers using the algorithm defined in the following steps:
- Select one or more headers in an HTTPReplyHeader header.
- If no Content-Type header is yet defined, create one by using
a non-empty value in the ContentType property.
- Select one or more headers in an HTTPResponseHeader header (an
HTTPResponseHeader header is propagated on return from an HTTPRequest node).
- If no Content-Type header is yet defined, create one with the
default value text/xml; charset=ccsid of
the message body.
- Create or overwrite the Content-Length header.
Attention: The HTTPReply node always rewrites
the Content-Length header, even if you have cleared Generate default HTTP headers from reply
or response. This action ensures that the content is
correct.
If an HTTPReplyHeader header section existed
in the message received by the HTTPReply node, and the Output
terminal of the HTTPReply node
is connected, the HTTPReplyHeader header section is updated
with all changed or added values.
- Setting Generate default HTTP
headers from input for the HTTPRequest or HTTPAsyncRequest node
- If you select Generate default
HTTP headers from input in the HTTPRequest or
HTTPAsyncRequest node
properties, the node includes a minimum set of headers in the
request that is sent to the server.
To explicitly set headers,
create them in an HTTPRequestHeader header. For example, a
Compute node propagating a
message in the XMLNSC domain can modify the Content-Type as
follows:
CALL CopyMessageHeaders();
SET OutputRoot.HTTPRequestHeader."Content-Type" = 'text/xml';
SET OutputRoot.XMLNSC = InputRoot.XMLNSC;
Do not
use the ContentType property to set the Content-Type unless you are
working in the MIME domain. The ContentType property is intended
to set the value of Content-Type used in MIME.
The full
set of HTTP headers used in the request is built by selecting
the headers using the algorithm defined in the following steps:
- Set the Host header, based on either the request URL or the incoming
HTTPRequestHeader header section of the message.
- Select one or more headers in an HTTPRequestHeader header.
- If no Content-Type header is yet defined, create one by using
a non-empty value in the ContentType property.
- Select one or more headers in an HTTPInputHeader header (an HTTPInputHeader
header is created automatically by an HTTPInput node).
- If no Content-Type header is yet defined, create one with the
default value text/xml; charset=ccsid of
the message body
- If no SOAPAction header is yet defined, create one with the default
value ''.
- Create or overwrite the Content-Length header.
Attention: The HTTPRequest or
HTTPAsyncRequest node
always rewrites the Content-Length header, even if you have cleared Generate default HTTP headers from
input or request. This action ensures that the content
is correct.
If an HTTPRequestHeader header exists
in the received message, the HTTPRequestHeader header is updated
with all changed or added values.