Http Client

Description

The HttpClient service performs HTTP operations such as GET and POST against a remote service. It can be used to retrieve remote web pages or interact with web services.

It supports:

  • GET, POST, PUT, DELETE and HEAD methods
  • HTTPS and port specification.
  • Authentication
  • Parameters
  • Headers
  • Data

The service deals with basic authentication and redirects which may require more than one HTTP request. It will perform redirects after a POST or a PUT, not just a GET or HEAD.

Input

<HttpClient>
  <method>GET|POST|PUT|DELETE|HEAD|OPTIONS|TRACE</method>
  <url/>
  <httpUser/>
  <httpPassword/>
  <preemptiveAuthentication>false|true</preemptiveAuthentication>
  <allowSelfSigned>false|true</allowSelfSigned>
  <allowAnyHost>false|true</allowAnyHost>
  <ParameterList>
    <Parameter>
      <name/>
      <value/>
      <file/>
      <fileName/>
    </Parameter>
  </ParameterList>
  <parameterEncoding>url|form|multipart</parameterEncoding>
  <HeaderList>
    <Header>
      <name/>
      <value/>
    </Header>
  </HeaderList>
  <data/>
  <multipart/>
  <returnResponse/>
  <outputFile>filename</outputFile>
  <base64>false|true</base64>
</HttpClient>

All parameters other than url are optional. Parameters can be encoded in the URL or passed in the parameter list. <method> defaults to GET.

The service encodes parameters, but does not encode data.

The url should contain the scheme (http or https), optional port number and optional file path, e.g. https://www.aservice.net:8443/dir/resource/_search

The url may contain parameters. Alternatively, parameter names and values can be passed using the <Parameter> element, which repeats.

How the parameters in the <Parameter> element are dealt with is controlled by the parameterEncoding element:
  • url – add parameters to the url.
  • form – send parameters in the data using form encoding.
  • multipart – send parameters in the data using multipart/form-data encoding. Parameters may contain a <file> element in place of a value, which specifies a file path, and an optional <fileName>, which specifies an alternative file name.

form and multpart should only be used for POST and PUT requests.

The request can contain many headers. Further headers may be added by the HttpClient processing.

Request data can be passed using the data element.

The httpUser and httpPassword parameters can be used for requests that require authentication, and should work for Basic and Digest authentication (and possibly other types). Set preemptiveAuthentication to send authentication tokens with the original request. This only makes sense for basic authentication and using https; for this reason it defaults to false.

Set allowSelfSigned to true to allow self-signed SSL certificates. Also set allowAnyHost to allow SSL certificates for the wrong host. This is intended primarily for testing.

data is only passed for POST and PUT requests; it is ignored for other methods. It can contain a string or an XML element which will be converted to a string. It cannot be set if parameter encoding is form or multipart (since these send the parameters in the request data).

Setting returnResponse to true will return the body of the response as the output from the service, or raise an error if it is not valid XML.

Setting outputFile to a file name will write the body of the response to the given file, and not return a response. Cannot be used with returnResponse or base64.

Setting base64 to true will return the response bytes encoded using base64. This cannot be used in conjunction with returnResponse. Use this to retrieve binary files.

Output

<HttpClient>
  <errorNumber>0</errorNumber>
  <status/>
  <HeaderList>
    <Header>
      <name/>
      <value/>
    </Header>
  </HeaderList>
  <response/>
</HttpClient>

If returnResponse is true, the output will be the parsed response.

Errors

0 - Success (http code >= 200 and < 300)

101 - Not authorised (http code 401, 403)

102 - Not found (http code 404)

103 - Parameter error

100 - Other error (any other http code)

Class

com.metrici.xerula.HttpClientService, com.minimalit.paxina.HttpClientService

Notes

The documentation is for the service supported by class com.minimalit.paxina.HttpClientService. Within Metrici, this is wrapped by the service supported by class com.metrici.xerula.HttpClientService.

This service is identical unless the <file> or <outputFile> elements are used.

The <file> element is used to pass the node version reference of the a user file, rather than a file path. If the <file> element is used, the service requires credentials in order to read the files. If the <fileName> element is omitted, it is defaulted to the value of the File Name member of the file node, or, if this is not present, to a name based on the local reference of the file node and the value of the File Extension member.

Set the <outputFile> element to true to write the output to a file. Information about the file will be returned in the <response> element:

  • storageKey - the storageKey for the file
  • size - size of the file in bytes
  • fileName - name of the file, including file extension
  • extension - file extension
  • contentType - the content type of the file