Hypertext Transfer Protocol (HTTP)

Actions

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

  Input parameters

  • Url - (String) URL of the resource that you want to access. For example, http://www.rubicon.com/orders/orders.html.
    Important: The string must begin with http:// or https://.
  • method - (String) Specifies the HTTP method that you want to use. Valid values are as follows:
    • delete
    • get
    • head
    • options
    • patch
    • post
    • put
  • loadAs - (String) Form in which you want the httpRequest to return the response. Set to -
    • bytes (default) to return the body of the response as a byte[ ].
    • 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 keys mentioned here.
    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 with args, create a string element for each name-value pair. The name represents the key, and the value represents the data.

      With args, the HTTP request automatically URL-encodes name-value pairs, separates them with &, and adds ? for GET or HEAD requests. webMethods Integration defaults the content-type header to application/x-www-form-urlencoded, but you can specify a different content-type with a string or bytes variable.
  • String - (String) 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 a string by using a GET or HEAD. You do not need to include this character in the string.

    For POST, PUT or PATCH requests, the string is included in the body of the request sent to the specified URL.

  • bytes - (byte[ ]) 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.
    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 the string. The service encodes the data from the bytes element in the body of the post. For POST, PUT and PATCH, you can specify stream, bytes or mimeStream. If you specify more than one, the httpRequest ends with an exception.
  • mimeStream - (java.io.InputStream) 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 stream, bytes or mimeStream. If you specify more than one, the httpRequest ends with an exception.
  • stream - (java.io.InputStream) 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.
    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 stream, bytes or mimeStream. If you specify more than one, the httpRequest ends with an exception.
  • Encoding - (String) Character set in which the URL data parameters are encoded (args and string). Encoding is necessary to convert the string object to bytes for a POST request. 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) Authorization information that the http service submits when the resource specified in the 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) The username that is provided for requesting a protected resource. Mandatory when the type is set to Basic or Digest.
    • pass - (String) Password associated with user. Mandatory when the type is set to Basic or Digest.
    • token - (String) The access token to submit to the OAuth resource server. Mandatory when type is set to Bearer.
    • Headers - (Document) Fields that you want to explicitly override in the HTTP request header issued by the httpRequest service. Specify a key in the headers for each field you want to set, where the key name represents the header field and the key value represents its value.
    • timeout - (String) Time, in milliseconds, that webMethods Integration waits for a response from the remote server. The default is 30,000 milliseconds.
    • connectTimeout - (String) Time, in milliseconds, that webMethods Integration waits to connect to the remote server before the request is stopped. The default is 30000 milliseconds.
    • newSession - (String) Flag indicating whether a new session is created for this HTTP request. Set to no to use the current session or create one named (httpclient) when none exists, or yes to create a new session for the HTTP request.
    • followRedirect - (String) Indicates whether the outbound request follows a redirect for response codes between 300–400. Set to yes (default) to automatically process the redirect, or no to return the response code and headers without processing it.

  Output parameters

  • encodedURL - The URL submitted by the httpRequest. It includes any arguments set in the args or string. If the remote server redirects the httpRequest, the encodedURL contains the URL that the request was redirected to.
  • 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 are returned when the loadAs input parameter is set to bytes.
    • stream - (java.io.InputStream, conditional) The body of the HTTP response is represented as an InputStream. The stream is returned when the loadAs input parameter is set to stream.

  Usage notes

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

  The httpRequest sends data or string input in the URL query for GET or HEAD methods, but includes it in the request body for POST, PUT or PATCH methods.

  If the HTTP response contains a 302 redirection status code and httpRequest is configured to redirect, the service follows the URL provided by the remote server. If the remote server redirects httpRequest to a different location, the encodedURL output parameter contains the URL 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 provided in an unsupported format for an HTTP method, the httpRequest ignores it. For example, the data or stream and data or mimeStream fields are not supported with DELETE. Any value that is specified for these fields is ignored when the method is set to DELETE.

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

  You can append query parameters directly to the URL input. Any values that are provided for data or args are also appended. For the GET method, the data or string value is included as well. 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 or type field is set to Digest) and the HTTP Server response includes the header field content-type. If the response does not contain the charset parameter, webMethods Integration uses the value of the netEncoding server configuration parameter as the default character set.

  For large datasets, use the compressData service to compress it before sending through httpRequest. For more information, see compressData.