REST Adapter

Properties   Configuration Settings  

The REST component provides a simple, ligthweight and fast way to communicate with RESTful web server.

Remarks

The REST adapter implements a highly configurable HTTP client that is capable of sending and receiving data to and from web servers. Support includes issuing simple GET requests as well as defining custom form and file parameters to be POSTed to server. URL defines the location to which the request is made.

The adapter supports HTTP 1.0, 1.1, and 2.0 which can be configured in the HTTPVersion property.

The HTTPMethod property defines the HTTP method to use. Possible values are:

• DELETE
• GET (default)
• HEAD
• POST
• PUT
• TRACE

Getting Data From the Server

In the REST Send Adapter, if HTTPMethod is set to GET the request is issued to the server specified by URL. Additional custom headers may be specified in the request by setting OtherHeaders.

The response received by the adapter will be used as the body of the submitted BizTalk message. In the case of the Send Adapter the response message is only returned when the adapter is configured in a solicit response port (recommended). The HTTP headers of the response are available via the TransferredHeaders context property of the message.

Sending Data To the Server

When HTTPMethod is set to POST or PUT data will be sent to the server. The RequestParams property specifies one or more parameters to add to the POST or PUT request. This property is only applicable when the HTTPMethod property is set to POST or PUT.

To specify additional parameters set this property to one or more name value pairs. Set one pair on each line. For instance:

The adapter will format a request with parameters slightly differently depending on whether the request is made by the Send or Receive adapter.

Note: To have complete control over the data being sent set PostData instead.

Send Adapter

When sending a POST or PUT request the BizTalk message body will always be used as the last parameter regardless of the values specified in RequestParams. If no values are set here then a request will be made with only one parameter which is the content of the message. Several examples and additional details follow.

Basic Example:

Setting the RequestParams to a value of:

Will result in a HTTP request like this:

Notice that the default "Content-Type" for the individual request parameters is "text/plain", and the default "Content-Type" for the message form variable is "application/octet-stream" and has no defined name attribute. See the following examples for further details.

Custom Request Parameter Content-Type Values:

When sending requests the RequestParams may optionally include a custom Content-Type value. The syntax is:

For instance setting RequestParams to a value of:

Will result in a HTTP request like:

Note the updated Content-Type header values for the "name1" and "name2" parameters.

Custom Content-Type and Name Values for the BizTalk Message Variable:

The default Content-Type value for the BizTalk Message form variable is "application/octet-stream" and no "name" attribute is defined in the Content-Disposition header. These can be explicitly defined in the ContentType and ContentFilename properties. These properties are applicable to the BizTalk Message form variable even if RequestParams is not set. For instance setting:

• ContentType to "text/html"
• ContentFilename to "myfile.txt"

And leaving RequestParams unspecified (no parameters) will result in a HTTP request like:

Parsing the Response

The ResponseXPath property may be set to traverse elements within the JSON document. This property implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML document. When this property is set, the adapter will parse the response and return the value at the specified location.

For example, let's say the response data from the original request is below.

The ResponseXPath property supports both XPath notation and JSONPath notation. For simplicitly, only the XPath notation is shown below. For more information and examples on notation schemes please see "Getting Started with JSON".

If you would like to return the value of element "name" from the operation, then set ResponseXPath to /json/bag/name/. Likewise, if you would like to return the value of the first element of the "items" array, then we can set ResponseXPath to /json/bag/items/[0]/ and the output will be camera.

Additional Settings

In addition to the basic operation as discussed above the adapter supports a variety of other settings that control authentication, proxy settings, and other behavior. Some of additional features include:

• Authentication (NTLM, Kerberos, Digest, Basic) via the AuthScheme, User, and Password properties.
• Full Proxy/Firewall support using the HTTPProxy and Firewall properties.
• CustomRequestMethod provides support for custom HTTP methods.
• Specify redirect behavior with FollowRedirects.
• Add cookies to the request via Cookies.
• Configurable UserAgent.
• And many more!

Sender Property List

---

The following is the full list of the properties of the sender adapter with short descriptions. Click on the links for further details.

Authorization	The Authorization string to be sent to the server.
AuthScheme	The authorization scheme to be used when server authorization is to be performed.
ContentFilename	Defines the filename of the content.
ContentType	Defines the Content-Type header in the request.
Cookies	The cookies to be sent in the HTTP request.
Firewall	A set of properties related to firewall access.
FollowRedirects	Determines what happens when the server issues a redirect.
HTTPMethod	The HTTP method used for the request.
HTTPProxy	A set of properties related to proxy access.
HTTPVersion	The HTTP version to use.
MaxPersistentConnections	The maximum number of simultaneous persistent connections when sending.
MaxThreads	The maximum number of threads that the component may consume.
MaxTransmissionBatchSize	The maximum number of messages that can be sent in a single batch.
OAuthAuthorization	OAuth Authorization Information.
Other	Defines a set of configuration settings to be used by the component.
OtherHeaders	Other headers as determined by the user.
Password	A password if authentication is to be used.
PostData	The data to be posted to the server.
RequestParams	Parameters to add to the POST or PUT request.
ResponseXPath	This property may be set to traverse elements within the JSON document.
RuntimeLicense	Specifies the component runtime license key.
SSLAcceptServerCert	Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.
SSLCert	The certificate to use for client authentication during the SSL handshake.
StatusLine	The first line of the last server response.
Timeout	A timeout for the component.
TransferredHeaders	The full set of headers as received from the server.
TransmitBatchMode	How the transmitter processes batches.
TransportLog	Tells the component where and how to report information about its operations.
URI	The Uniform Resource Identifier (URI) of the send port or receive location.
URL	The URL to which the request is made.
User	A user name if authentication is to be used.

Configuration Settings

---

The following is a list of configuration settings for the adapter with short descriptions. Click on the links for further details.

Accept	A list of acceptable MIME types for the request.
AcceptEncoding	Used to tell the server which types of content encodings the client supports.
AllowHTTPCompression	This property enables HTTP compression for receiving data.
AllowHTTPFallback	A list of acceptable MIME types for the request.
ChunkSize	Specifies the chunk size in bytes when using chunked encoding.
CustomRequestMethod	Specifies the HTTP method to be used.
EncodeURL	If set to true the URL will be encoded by the component.
IfModifiedSince	A date determining the maximum age of the desired document.
KerberosSPN	The Service Principal Name for the Kerberos Domain Controller.
LogDebugData	Whether to log debug data.
MaxRedirectAttempts	Limits the number of redirects that are followed in a request.
Pragma	A browser/server specific header line (optional).
Range	The byte-range to be sent to the server.
Referer	Referer URL/document (optional).
ResponseBodyAlwaysAvailable	Whether the response body is always available.
SubmitErrorAsMessage	Whether errors are submitted as BizTalk messages.
TransferredDataLimit	The maximum of data to be transferred.
UseChunkedEncoding	Enables or Disables HTTP chunked encoding for transfers.
UserAgent	Information about the user agent (browser).
ReuseSSLSession	Determines if the SSL session is reused.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuites	The cipher suite to be used in an SSL negotiation.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLIncludeCertChain	Whether the entire certificate chain is included in the SSLServerAuthentication event.
SSLSecurityFlags	Flags that control certificate verification.
TLS12SignatureAlgorithms	Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroups	The supported groups for ECC.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SupportedGroups	The supported groups for (EC)DHE key exchange.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
TcpNoDelay	Whether or not to delay when sending packets.
UseInternalSecurityAPI	Tells the component whether or not to use the system security libraries or an internal implementation.