1. Topics:
  2. Protocol reference
  3. |
  4. SMTP protocol
  1. Modules:
  2. NONE
  3. |
  4. Command line interface tasks

HTTP and HTTPS protocols

These protocols communicate with remote resources using HTTP or HTTPS.

The protocol configuration described in this topic allows an application to send HTTP and HTTPS requests to a remote resource. For more information about sending requests to remote resources, see Calling a remote resource. For information about configuring an IBM® WebSphere® sMash application to accept requests from clients using HTTPS, see SSL configuration.

Summary

Name
http and https
Description
Communicate with remote resources using HTTP or HTTPS.
Resource name
Must contain the URL of the remote resource, using http: or https:.
Operations
GET
HEAD
POST
PUT
DELETE

Example usage

The following example uses the Connection API to GET the contents of a document over HTTP:

try {
    Connection.Response resp = Connection.doGET("http://www.projectzero.org/");
    if ("200".equals(resp.getResponseStatus())) {
        String resposeBody = resp.getResponseBodyAsString();
        // Returned document is now in responseBody
    } else {
        // Handle status code other than "200" here
    }
} catch (Exception e) {
    // Handle exceptions here
}

See Using the Connection API for more information about using the Connection API and Working with HTTP or HTTPS services for more examples for HTTP and HTTPS.

Request and response format

GET, HEAD and DELETE operations

Request headers

HTTP headers to be included with the request. If a request header has multiple values, each value will sent to the server as a separate HTTP header.

The transport will automatically add a Host header containing the hostname and port specified in the request target URL. Any Host header specified by the application will be ignored.

Request body

No request body.

Response headers

HTTP headers to be received with the response.

Response body

InputStream containing the response.

The application can use Connection.Response.getResponseStatus() to obtain the string representation of the integer HTTP status code returned by the remote service.

POST and PUT operations

Request headers

Request header name Comments
Content-Type Request body content type. If not specified, text/plain; charset=UTF-8 will be assumed.
Other headers Other HTTP headers to be included with the request. If the request header has multiple values, each value will sent to the server as a separate HTTP header.

If the request body is an instance of MultipartBody then the values of the following request headers will be replaced with values appropriate for the MIME encoded request body:

  • MIME-Version
  • Content-Type
  • Content-Transfer-Encoding

The transport will automatically add a Host header containing the hostname and port specified in the request target URL. Any Host header specified by the application will be ignored.

Request body

Request body type Comments
String or Reader Converts to binary for transmission according to encoding in Content-Type header. If Content-Type has multiple values, the first value will be used. If charset not specified, the HTTP default encoding, ISO-8859-1, will be used.
byte[] or InputStream Transmits binary data without conversion.
MultipartBody Encode multi-part body using MIME.
Other types Calls toString() and processes result as String.

The http and https protocols also support applications using Connection.getRequestOutputStream() without additional buffering of the request body.

Response headers

HTTP headers to be received with the response.

Response body

InputStream containing the response.

The application can use Connection.Response.getResponseStatus() to obtain the string representation of the integer HTTP status code returned by the remote service.

Configuration

Parameter Description Default
userid Basic authentication user ID. None set.
password Basic authentication password. (XOR strings are supported) None set.
proxyHost HTTP proxy hostname. (Not supported for https) No proxy.
proxyPort HTTP proxy port. 8080
proxyUserid Proxy authentication user ID. None set.
proxyPassword Proxy authentication password. (XOR strings are supported) None set.
connectionTimeout Connection timeout, in seconds. 15
writeTimeout Timeout for individual write operation, in seconds. 60
readTimeout Timeout for individual read operation, in seconds. 60
httpsConfig Outbound HTTPS configuration name. (Not supported for http) defaultConfig (https only)

If the userid configuration parameter is supplied, the userid and password values will be included in the request using the basic authentication mechanism. This will replace any Authorization header value included in the request headers. Similarly, proxyUserid and proxyPassword will be used to replace any Proxy-Authorization header.

Protocol configuration can be applied to the connection request using various mechanism, as described in Configuring protocols.

HTTPS configuration

The httpsConfig protocol configuration parameter is used for requests using the https protocol to specify the certificate and trust for the outbound HTTPS connection.

The value of httpsConfig names an outbound HTTPS configuration that has been defined as /config/connection/https/ configName. If no httpsConfig value was associated with the request using the mechanisms described in Configuring protocols the supplied configuration, defaultConfig, will be used.

The behavior of the defaultConfig configuration depends on whether the application includes the zero.core.webtools dependency:

  • If zero.core.webtools is included, a development and test configuration is assumed:
    • Outbound HTTPS connections using defaultConfig will not perform any checks to validate the identity of the remote server.
  • If zero.core.webtools is not included, a simple trust configuration is assumed:
    • Outbound HTTPS connections using defaultConfig will check that the remote sever presents a valid certificate signed by one of a selection of well-known certificate authorities.

Regardless of the configuration, defaultConfig does not present a client certificate to the remote server.

The defaultConfig may be sufficient for development and simple trust scenarios but there may be occasions when more specific HTTPS configuration is required. For example:

  • More specific trust configuration is required to confirm the identity of the remote server.
  • A key store is required in order to present a client certificate to the remote server.

An example of an HTTPS configuration can be seen in the following configuration extract. This configuration could be selected for an HTTPS request by setting httpsConfig to myHttpsConfig.

/config/connection/https/myHttpsConfig = {
    "trustStore" : "config/truststore.jks",
    "trustStorePassword" : "password",
    "trustStoreType" : "JKS"
}

The HTTPS connection configurations defined under /config/connection/https/ configName can contain the following properties:

Property Description Notes
trustStore File name of trust store to be used to validate server identity. Required.
trustStorePassword Trust store password. (XOR strings are supported) Required.
trustStoreType Trust store type. Required.
keyStore File name of key store containing client certificate. Optional, default is no client certificate.
keyStorePassword Key store password. (XOR strings are supported) Required if keyStore is specified.
keyStoreType Key store type. Required if keyStore is specified.
disableTrustVerification If true, the outbound connection will not perform any checks to validate the identity of the remote server. Optional, default value is false

See the SSL configuration documentation in the zero.core developer's guide for more information about valid key store and trust store type values.

Version 1.0.0.3.25591