This topic provides reference information on HTTP Service Transports used in HCL Leap .
The HTTP Service Transport provides a mechanism to communicate with HTTP servers. The transport allows configuration of the URL to request, HTTP method to use, query parameters, and request headers. When combined with the Leap service mapping engine, the HTTP Service Transport extracts data from an HTTP response and makes it available to your application.
The HTTP Service Transport can be used to communicate with any standard HTTP server. There are some limits on what the HTTP Service Transport can provide, but in most cases, the HTTP Service Transport is all that is required to communicate with a basic HTTP server, or RESTful service.
The HTTP Service Transport has numerous parameters to configure it to talk to many HTTP Servers. In many cases, only a subset of the available parameters is needed. However, all the parameters can be used for any Service Description. The following sections provide a high-level outline of the parameters needed to configure specific parts of your HTTP request.
The HTTP Service Transport supports all the basic HTTP request methods, including: GET, PUT, POST, and DELETE. The HTTP Service Transport supports configuring the HTTP request method with the request-method parameter. If this parameter is missing, or does not contain a valid HTTP request method, then the default, GET is used.
The HTTP Service Transport constructs the URL by starting with the value of request-url and appending postfixes. If request-url-postfix is present, its value is appended to the value of request-url. Before appending, the HTTP Service Transport URL encodes the value of request-url-postfix if the request-url-postfix-encoded flag is not present or if its value is anything other than true. Encoding allows values containing characters that are not valid to be placed into the URL without any harm. Choosing to not encode a value allows it to be appended without modification to the URL.
For example, consider a Service Description that requires the path to a file as input. Since the path might contain slash (/) characters that must be preserved, then request-url-postfix-encoded is set to true. This instructs the HTTP Service Transport to leave the value alone. However, another Service Description might need to include a text string as a path component. In this case, the slash (/) or any other characters are encoded such that they do not interfere with the path. In this second case, the request-url-postfix-encoded parameter is set to false or omitted from the Service Description.
In some cases, having a single postfix does not provide enough flexibility. Therefore, the dynamic parameters request-url-postfix-Nand request-url-postfix-N-encoded are used. The N in each of these parameters refers to its order. During processing, the HTTP Service Transport appends the value of these parameters starting with 0 until it finds a missing parameter. As with the single postfix, encoding is optionally performed on each of the parameters before it is added if the value of the request-url-postfix-N-encoded flag is not present or contains any value other than true.
For example, if the Service Description contains parameters called request-url-postfix-0, request-url-postfix-1, and request-url-postfix-3, only request-url-postfix-0 and request-url-postfix-1 are appended to the URL.
While building the request URL if a parameter called request-url-postfix is found, the dynamic parameters are ignored. The Service Description developer must make a conscious choice to use these dynamic parameters.
The HTTP Service Transport supports HTTP Basic and HTTP Digest authentication schemes. There are three mechanisms through which the credentials can be configured: hard coded in the Service Description, provided through the Java 2 Connector (J2C) Authentication Credentials provider, or provided at run time through the Basic Credentials Provider.
Name | Description | Mandatory | Type | Default |
---|---|---|---|---|
request-url | Base URL to request. | Yes | String | |
request-method | HTTP verb to use when making the request. Acceptable values are GET, PUT, POST, or DELETE. | No | String | GET |
request-url-postfix | Postfix to append to the value of request-url. | No | String | N/A |
request-url-postfix-encoded | Flag indicating whether the value of request-postfix is encoded. If this parameter is missing or is set to false, the value is URL encoded. | Yes | Boolean | FALSE |
request-url-postfix-N | The N postfix to append to the value of request-url. This parameter is only considered if request-postfix is not present. | No | String | N/A |
request-url-postfix-N-encoded | Flag indicating whether the value of the corresponding request-postfix-N is encoded. If this parameter is missing or set to false, the value is URL encoded. | No | Boolean | FALSE |
request-header-x | The value for the request header x. For example, request-header-accept creates a request header called accept. | No | String | N/A |
request-query-x | The value for the query parameter called x. For example, request-query-term creates a query parameter called term. | No | String | N/A |
request-entity | The body of the request to send. The UTF-8 character set is used. | No | String | N/A |
Name | Description | Type |
---|---|---|
response-code | HTTP status code returned by the server. This could be any of the standard values, for example, 200, 400, and 500, or a non-standard code returned by the server. | Integer |
response-message | HTTP status message associated with the HTTP status code. The value of this parameter is determined by the server. Generally, this message is a standard status message, for example, OK, Not Found, or Server Error. | String |
response-header-x | The value of the response header named x in lowercase. For example, if the response contains the response header Content-Type: text/html then response-header-content-type contains the value text/html. | String |
response-entity | The entire response body from the HTTP request. It is assumed that the response uses the UTF-8, or ASCII character set. | String |
<?xml version="1.0" encoding="utf-8"?>
<serviceDescription>
<id>make-http-request</id>
<defaultLocale>en-us</defaultLocale>
<transportId>HTTPServiceTransport</transportId>
<name xml:lang="en-us">Make an HTTP Request</name>
<description xml:lang="en-us">Makes an HTTP request to the configured URL and returns the result</description>
<inbound>
<parameters>
<parameter>
<id>request-url</id>
<name xml:lang="en-us">URL</name>
<description xml:lang="en-us">URL to request.</description>
<mandatory>true</mandatory>
<type>STRING</type>
</parameter>
<parameter>
<id>request-method</id>
<name xml:lang="en-us">Method</name>
<description xml:lang="en-us">HTTP method to use, one of GET, PUT, POST, or DELETE.</description>
<mandatory>true</mandatory>
<type>STRING</type>
</parameter>
</parameters>
</inbound>
<outbound>
<parameters>
<parameter>
<id>response-entity</id>
<name xml:lang="en-us">Response</name>
<description xml:lang="en-us">Response returned by making a request to the configured URL.</description>
<mandatory>false</mandatory>
<type>STRING</type>
</parameter>
</parameters>
</outbound>
</serviceDescription>