Hypertext Transfer Protocol (HTTP)

httpRequest: Make HTTP or HTTPS requests to the specified server.

Input Parameters

• url: String Optional - URL of the resource that you want to access. For example: http://www.rubicon.com/orders/orders.html.

  Important: This string must begin with http:// or https://.

• method: String - Specifies the http method that you want to use. Valid values are:

  • delete
  • get
  • head
  • options
  • patch
  • post

  • put

• loadAs: String Optional - Form in which you want the httpRequest to return the response. Set to:

  • bytes to return the body of the response as a byte[ ]. This is the default.

  • stream to return the body of the response as a java.io.InputStream.

• data: Document - Data that you want the httpRequest to submit with the request. Specify data by using one or more of the following keys.

  Important: When you use more than one key, args is appended first and string is appended last.

  • args: Name-value pairs that you want this service to submit to the resource in url. You can use args to submit data through the POST, PUT, PATCH, GET, DELETE, or HEAD methods. To specify data by using args, create one String element for each name/value pair that you want to submit, where the element’s name represents the name portion of the pair and the element’s value represents the value portion of the pair. When using args, the HTTP request automatically URL-encodes the name-value pairs, inserts '&' between pairs, and prefixes the query string with '?' for GET or HEAD requests. IBM webMethods Integration automatically sets the Content-Type header to application/x-www-form-urlencoded, but if you need a different Content-Type, it must be specified by using a string or bytes variable.

• string: String Optional - Text that you want the httpRequest service to submit to the resource in url. You can use string to submit data through the POST, PUT, PATCH, GET, or HEAD methods. If you use string to submit data, make sure that you specify the string exactly as you want it presented in the httpRequest. (If you are using the GET or HEAD method, make sure that you URL-encode the contents of the string.
  Note: When you use string, the httpRequest service will automatically prefix the entire query string with "?" if it submits the data in string by using a GET or HEAD. You do not need to include this character in the string.

  When performing a POST, PUT, or PATCH, string is submitted to the resource defined by url as the body of the request message.

• bytes: byte[ ] Optional - Data that you want this service to submit to the resource in url. You can use bytes to submit data using the DELETE, POST, PUT, or PATCH methods only.
  Note: When you use bytes and another element (args or string) to specify data, the service appends the data from the args or string element to url. The service appends args to the url first and then string. The service encodes the data from the bytes element in the body of the post. > For POST, PUT, and PATCH, you can specify only stream, bytes, or mimeStream. If you specify more than one, the httpRequest ends with an exception.

• mimeStream: Java™.io.InputStream Optional - MIME or SMIME message that you want this service to submit to the resource in url. It contains both headers and content. The headers in the mimeStream are appended to the http headers. You can use mimeStream to submit data by using the POST, PUT, or PATCH methods only.

  Note: For POST, PUT, and PATCH, you can specify only stream, bytes, or mimeStream. If you specify more than one, the httpRequest ends with an exception.

• stream: java.io.InputStream Optional - Data that you want the httpRequest service to submit to the resource in url. You can use stream to submit data by using the POST, PUT, or PATCH methods only.

  Note:

  When you use stream and another element (args, string or bytes) to specify data, the service appends the data from the args or string element to url. The service appends args to url first and string last. The service encodes the data from the stream element in the body of the post. For POST, PUT, and PATCH, you can specify only stream, bytes, or mimeStream. If you specify more than one, the httpRequest ends with an exception.

• encoding: String Optional - Character set in which the URL data parameters are encoded (args and string). Encoding is required to correctly convert the String object to bytes when generating the URL for a post. Specify an IANA-registered character set (for example, ISO-8859-1). If this variable is null, the default JVM encoding is used. Because string is used in the body of the post and not used for building the URL, you do not need to specify encoding for the data parameter string.

• auth: Document Optional - Authorization information that the http service will submit if the resource specified in url is protected.

  • type: String - Type of authentication scheme that you want this service to use when it submits this request. Set to "None" for no authentication (default), "Basic" for username and password, "Bearer" for OAuth authorization, or "Digest" for password digest authentication.

  • user: String - User name that this service will submit when requesting a protected resource. This is mandatory when the type is set to Basic or Digest.

  • pass: String - Password associated with user. This is mandatory when the type is set to Basic or Digest.

  • token: String - The access token to submit to the OAuth resource server. Required only when type is set to Bearer.

  • headers: Document Optional - Fields that you want to explicitly override in the HTTP request header issued by the httpRequest service. Specify a key in headers for each header field that you want to set, where the key’s name represents the name of the header field and the key’s value represents the value of that header field.

  • timeout: String Optional - Time, measured in milliseconds, that IBM webMethods Integration waits for a response from the remote server before timing out and ending the request. The default value is 30000 milliseconds.

  • connectTimeout: String Optional - Time, measured in milliseconds, that IBM webMethods Integration waits to connect to the remote server before timing out and terminating the request. The default value is 30000 milliseconds.

  • newSession: String Optional - Flag indicating whether a new session will be created for this HTTP request. Set to "no" to use the current session or create one named "(httpclient)" if none exists, or "yes" to create a new session for the HTTP request.

  • followRedirect: String Optional - Whether the outbound request follows a redirect when receiving a response code between 300 and 400. Set to "yes" to follow the redirect (default) or "no" to return the response code and headers without following the redirect.

Output Parameters

• encodedURL: String - The URL that was submitted by httpRequest. This will contain any argument set in args or string. If the remote server redirected httpRequest to a different location, encodedURL will contain the URL that the httpRequest submitted to the server to which it was redirected.

• header: Document Conditional - HTTP response headers.

  • lines: Document - Fields in the response header, where key names represent field names and values represent field values.

  • status: String - HTTP status code of the response.

  • statusMessage: String - HTTP status message of the response.

• body: Document - Body of the HTTP response.

  • bytes: byte[ ] Conditional - Body of the HTTP response represented as a byte[ ]. bytes is returned only when the loadAs input parameter is set to bytes.

  • stream: java.io.InputStream Conditional - The body of the HTTP response represented as an InputStream. stream is returned only when the loadAs input parameter is set to stream.

Usage Notes

For the GET, HEAD, and OPTIONS methods, the httpRequest sends a URL only. The service does not send a body.

The httpRequest sends the data/string input in the query of the URL when using the GET or HEAD methods, but sends the input as the body of the request when using the POST, PUT or PATCH methods.

When the HTTP response contains the HTTP 302 redirection status code and the httpRequest is configured to redirect, the service redirects the request to the URL provided by the remote server. If the remote server redirected httpRequest to a different location, the output parameter encodedURL will contain the URL that http submitted to the server to which the service was redirected.

When the method input variable is DELETE, you can supply a value in the data/bytes input variable. The http service transmits the value in the body of the request to the remote server

If data is supplied in a format that is not supported with an HTTP method, the httpRequest ignores the data. For example, use of the data/stream and data/mimeStream input fields is not supported with DELETE. If the data/stream or data/mimeStream input fields specify a value when method is set to DELETE, the httpRequest ignores data/stream or data/mimeStream.

For POST, PUT and PATCH, if a value is supplied for data/args the httpRequest sets the Content-Type header for the request to application/x-www-form-urlencoded. The service ignores a Content-Type value supplied using a name/value pair in headers.

You can append query parameters directly to the url input parameter value. If you do this, any value supplied for data/args will be appended. For the GET method, the data/string value would also be appended. For example, these inputs:

• url = http://example-host:8080/getOrders?cust=116
• data/args= {{“since”, “20180201”}, {“greaterThan”, “250.00”}}

Result in httpRequest sending this URL: http://example-host:8080/getOrders?cust=116&somce=20180201&greaterThan=250.00.

When the httpRequest service submits a password digest for authentication (that is, the auth/type field is set to Digest) and the HTTP server response includes the header field “Content-Type” but does not contain the charset parameter, IBM webMethods Integration uses the value of the netEncoding server configuration parameter as the default character set.

If you have a large set of data and want to compress the data before sending it through httpRequest, then you can use compressData service to compress the data and then send it. For more information on compressData, see compressData.