For detailed information about the scripting parameters and methods for HTTP objects that are discussed here, please refer to Scripting Parameters and Methods - HTTP Requests.

HTTP Connection

The first step in using the HTTP object in a script Action or Map event, is to identify the HTTP Connection object that contains the configuration details of the HTTP service to be invoked. The properties of this HTTP Connection object will include the appropriate OAuth credentials, and any header or query parameter values that may be required for a successful connection.

Within the script, the HTTP Connection is identified by name, by assigning that name to the string-type Connection parameter.

Declaration: HTTP.Connection: String;

In this example, the HTTP Connection called NZ Customs Rates will be used, so the script would include the following line.

HTTP.Connection := 'NZ Customs Rates';

Open The Request Line

After establishing the HTTP Connection to be used, the next step is to open the communication line to the server. This is done with the HTTP.Open method which tells the HTTP object the method you want to use, and the path to request.

Opening a request on the HTTP object does not generate an actual request, it simply tells the HTTP object that it should prepare itself for a future request. After a request has been opened, any information about the response to any previous request is lost.

Opening a request requires that two pieces of information are provided – the parameter aMethod which is the HTTP method (command) that will be issued by the request, such as GET, PUT, or POST, and the aURL parameter being the URL that the request will be issued against.

Declaration: HTTP.Open(const aMethod: String; const aURL: String);

NOTE: The hostname and port e.t.c. are all specified by the HTTP Connection object and are not part of the URL specified here, which should consist only of the document path for the request.

The document path specified is appended to any root path specified on the HTTP Connection associated with the HTTP object.

aURL could be blank, could refer to a declared variable, or could be a document path that is to be appended.

An example where a declared variable for the document path urlPath is used as a reusable value.

urlPath := 'api/postcode/search.xml';
 
...
HTTP.Open('GET', urlPath);

An example where the contacts path is appended.

HTTP.Open('GET', 'contacts');

Using NZ Customs Rates as the example connection, the following HTTP.Open line would follow the HTTP.Connection instruction.

HTTP.Open('GET',''); //Performs a GET with NO path addition

HTTP.Header And HTTP.Param

Custom request Headers may be specified in two places, while request Parameters may be specified in three different places

  • For headers and parameters that will be applied to most or all requests issued to a given HTTP Connection, it is necessary to define those headers and/or parameters on the HTTP Connection object itself. The HTTP Connection object in the configuration would be edited in the usual fashion, by identifying any headers and/or parameters and applying any default or initial values as required. Values for headers and parameters specified here may include tag references which will be resolved at the time that they are applied. If the processed value of a header or parameter is empty and that header or parameter is identified as being optional, then that header or parameter will not be included.  Please refer to HTTP Connections for more detail.

  • The second place where request headers and parameters may be specified is using script, via the Header and Parameter properties of the HTTP object itself.

  For example.

HTTP.Header['If-Modified-Since'] := '2013-03-15T00:00:00';
HTTP.Param['where'] := 'IsCustomer==true';

Or,

q := '44 high';
...
HTTP.Param['q'] := q;

Or,

HTTP.Header['AUTH-KEY'] := P_NZPost['API_KEY'].Value;

  • For parameters only, a third option is to specify the parameters directly by setting the QueryString property of the HTTP object. When the QueryString is set directly in this fashion, any and all parameter values set via the connection or the HTTP parameters are ignored. Only the specified QueryString is applied.

  For example.

HTTP.QueryString := 'enabled=true&id=CUST0001';

Or as below, urlQuery represents the query string you would pass the script by way of a reusable variable.

urlQuery := 'q=Waitakere&region=Auckland';
...
HTTP.QueryString := urlQuery;

HTTP.Header And HTTP.Param Values

 Where header and parameter values are applied, HTTP Connection headers and parameters are applied first, followed by any headers or parameters specified in script on the HTTP object directly.

Scripted header/parameter values therefore override and overwrite any values specified on the HTTP Connection object.

To remove a header or parameter specified by an HTTP Connection object without actually editing the HTTP Connection itself, simply set the value of that header or parameter to an empty string using two (2) single quote marks with no middle space ( '' ) in the script, as shown below. 

HTTP.Param['where'] := '';

Empty HTTP.Header or HTTP.Param Values

The precise behaviour of an empty header or parameter is governed by two further properties of the HTTP object.

For Headers, the options are quite simple - empty headers are either included in a request or they are excluded.

Accordingly, the HTTP object has a simple SendEmptyHeaders property that determines whether or not headers with no value are included in any request. This is set to the boolean value of FALSE by default, so that if a header has no value then that header will not be included in the request. To include such empty headers, change this property to TRUE as below.  

HTTP.SendEmptyHeaders := TRUE;

With empty parameters, the situation is a little more complex. A server or service might require that empty parameters are included as complete parameter declarations with their empty values, that they be included as flags, or that they not be included at all.

Accordingly, the property that governs the sending of empty parameter values is a property called EmptyParamRule with only three possible values - epExclude, epInclude and epIncludeAsFlag.

The effect of each of these values on the sending of empty parameters is illustrated in the end-line comments of the following code.

HTTP.Param['paramA']  := 'valueA';
HTTP.Param['enabled'] := '';
HTTP.Param['paramB']  := 'valueB';
...
HTTP.EmptyParamRule := epExclude;        // =>  http://host.com/url?paramA=valueA&paramB=valueB
 
HTTP.EmptyParamRule := epInclude;        // =>  http://host.com/url?paramA=valueA&enabled=&paramB=valueB
 
HTTP.EmptyParamRule := epIncludeAsFlag;  // =>  http://host.com/url?paramA=valueA&enabled&paramB=valueB

The correct setting of the SendEmptyHeaders and EmptyParamRule properties will vary according to the needs and expectations of the particular web service or server involved in each case.

Supplying Request Content

If the request that is opened requires any body or content to be supplied, this must be written to the Content stream, before the request is sent as illustrated.

// Where 's' is some string containing the request body
...
HTTP.Content.Write(s, Length(s));

The Content property is a stream, and the request content should be written to that stream using the usual methods for writing data to a stream.

Content on the HTTP script object may now be set in one of three ways -

  1. HTTP.Content.Write( ... ) The usual supported methods of the HTTP.Content stream object may be used to write data to the content.

  2. HTTP.ContentAsString Allows the content of the HTTP request to be set by assigning a string value. When assigning a value in this way, the existing contents of the Content Stream are entirely replaced.  The use of HTTP.ContentAsString would be the more usual method to use.

  3. HTTP.Content Allows the content of the HTTP request to be set by assigning the content of some other stream. When assigning stream content in this way, the contents of the stream being assigned are copied to the HTTP content object, entirely replacing any content already present in the Content stream. Further data written to the assigned stream after being assigned to Content will not be reflected in the HTTP.Content unless re-assigned to stream again, as shown in the example below. 

HTTP.Content := stream;
 
// .. Add an integer to the stream ..
stream.Write(someInteger, sizeof(Integer));
 
// Re-assign the stream to update the HTTP Content
HTTP.Content := stream;

If the assigned stream object was created by the script, then the script must Free that stream object as usual. The HTTP object will look after the Content stream which must not be Free'd. 

Sending the Request

Once a request has been opened, all header and parameter values specified, and any request content supplied, the request may be sent using the Send method of the HTTP object, as below.

HTTP.Send;

For examples of HTTP requests, please visit HTTP Request Examples.