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 Using the connection infrastructure.
  • For information about configuring an IBM® WebSphere® sMash application to accept requests from clients using HTTPS, see SSL configuration.

Protocol 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

This section details the headers and body types for the requests and responses of the supported operations.

GET, HEAD and DELETE operations

The GET, HEAD and DELETE operations send a HTTP or HTTPS request with no body. The request method is the specified operation.

Request headers

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

  • The transport automatically adds a Host header containing the hostname and port specified in the request target URL. Any Host header specified by the application is ignored.
  • The transport automatically adds cookie headers for those listed in /connection/request/cookies.

Request body

No request body.

Response headers

HTTP headers to be received with the response.

Valid cookies set by the response headers are listed in /connection/response/cookies.

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

The POST and PUT operations send a HTTP or HTTPS request containing a body. The request method is the specified operation.

Request headers

Request header name Comments
Content-Type Request body content type. If not specified, text/plain; charset=UTF-8 is assumed.
Other headers Other HTTP headers to be included with the request. If the request header has multiple values, each value is 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 are replaced with values appropriate for the MIME encoded request body:
    • MIME-Version
    • Content-Type
    • Content-Transfer-Encoding
  • The transport automatically adds a Host header containing the hostname and port specified in the request target URL. Any Host header specified by the application is ignored.
  • The transport automatically adds cookie headers for those listed in /connection/request/cookies.

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 then the first value is used. If charset not specified then the HTTP default encoding, ISO-8859-1, is 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.

Valid cookies set by the response headers are listed in /connection/response/cookies.

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 are included in the request using the basic authentication mechanism. This replaces any Authorization header value included in the request headers. Similarly, proxyUserid and proxyPassword are 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 then the supplied configuration, defaultConfig, is 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 do 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 check that the remote server 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 can be sufficient for development and simple trust scenarios but there might 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 does not perform any checks to validate the identity of the remote server. Optional, default value is false

See the SSL configuration topic for more information about valid key store and trust store type values.

Version 1.1.31300