--- url: /statelake/scripting-reference/http-scripting/http-requests.md --- # HTTP Requests 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](/statelake/scripting-reference/http-scripting/http-requests/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. ```pascal 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); ::: info 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. ```pascal urlPath := 'api/postcode/search.xml'; ... HTTP.Open('GET', urlPath); ``` An example where the **contacts** path is appended. ```pascal HTTP.Open('GET', 'contacts'); ``` Using **NZ Customs Rates** as the example connection, the following **HTTP.Open** line would follow the **HTTP.Connection** instruction. ```pascal 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](/statelake/administering-statelake/designer/data-connections/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. ```pascal HTTP.Header['If-Modified-Since'] := '2013-03-15T00:00:00'; HTTP.Param['where'] := 'IsCustomer==true'; ``` Or, ```pascal q := '44 high'; ... HTTP.Param['q'] := q; ``` Or, ```pascal 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. ```pascal 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. ```pascal urlQuery := 'q=Waitakere®ion=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. ::: info 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. ```pascal 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. ```pascal 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. ```pascal HTTP.Param['paramA'] := 'valueA'; HTTP.Param['enabled'] := ''; HTTP.Param['paramB'] := 'valueB'; ... HTTP.EmptyParamRule := epExclude; // => http://host.com/url?paramA=valueA¶mB=valueB HTTP.EmptyParamRule := epInclude; // => http://host.com/url?paramA=valueA&enabled=¶mB=valueB HTTP.EmptyParamRule := epIncludeAsFlag; // => http://host.com/url?paramA=valueA&enabled¶mB=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. ```pascal // 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. ```pascal 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. ```text HTTP.Send; ``` For examples of **HTTP** requests, please visit [HTTP Request Examples](/statelake/scripting-reference/http-scripting/http-requests/http-request-examples).