HTTP Built-ins ¶
HTTP Built-ins create HTTP requests and responses. They are primarily used for Request Builder functions (get
, post
, put
delete
, head
or options
) and their available builder methods.
If this is your first time using HTTP Built-ins, please visit our HTTP Built-ins Tutorial.
More complex functionality and specific use cases are described in the following sections:
Request Builder Functions¶
The Request Builder is an object that builds a well-formed HTTP request from the parameters passed to it. Its functions build requests and take a URI as parameter. They may be chained with any non-static RequestBuilder
methods as described in the Apache documentation. All Request Builder functions must be completed with the .build()
.
After building and sending the request message, the server responds with an Http response message, called by executeHttpRequest
.
Note:
When specifying the URI, it should always begin with the http://
or https://
prefix. Otherwise an error will occur.
HTTP Get ¶
Requests data from the specified web server using the GET
method.
Syntax
1 | <result RequestBuilder> := Http.get(<uri String>) |
Returns
The request builder instance that helps to build a request to the specified URI using the GET
method.
Parameter
- uri - The URI of the server the data is being returned from
Example
1 2 3 4 5 6 | request := Http.get("http://www.qitasc.com") .addHeader("Content-Type", "text/plain") .addParameter("username", "User") .addParameter("password", "Secret!") .build() response := Http.executeHttpRequest(request) |
HTTP Post ¶
Requests data from the specified web server using the POST
method.
Syntax
1 | <result RequestBuilder> := Http.post(<uri String>) |
Returns
The enclosed data entity from the post request.
Parameter
- uri - The URI that the enclosed data is being sent to
Example
1 2 3 | request := Http.post("http://www.qitasc.com") .build() response := Http.executeHttpRequest(request) |
HTTP Put ¶
Requests data from the specified web server using the PUT
method.
Syntax
1 | <result RequestBuilder> := Http.put(<uri String>) |
Returns
The enclosed data from the PUT
request.
Parameter
- uri - The URI that the enclosed data is being sent to
Example
1 2 3 | request := Http.put("http://www.qitasc.com") .build() response := Http.executeHttpRequest(request) |
HTTP Delete ¶
Requests data from the specified web server using the DELETE
method.
Syntax
1 | <result RequestBuilder> := Http.delete(<uri String>) |
Returns
The resource to be deleted.
Parameter
- uri - The URI of the resource being deleted
Example
1 2 3 | request := Http.delete("http://www.qitasc.com/oldfiles") .build() response := Http.executeHttpRequest(request) |
HTTP Head ¶
Requests data from the specified web server using the HEAD
method.
Syntax
1 | <result RequestBuilder> := Http.head(<uri String>) |
Returns
The request builder instance that helps to build a request to the specified URI using the HEAD
method.
Parameter
- uri - The URI of the resource whose header is requested
Example
1 2 3 | request := Http.head("http://www.qitasc.com") .build() response := Http.executeHttpRequest(request) |
HTTP Options ¶
Requests data from the specified web server using the OPTIONS
method.
Syntax
1 | <result RequestBuilder> := Http.options(<uri String>) |
Returns
The methods returned by the URI's server.
Parameter
- uri - The server's URI
Example
1 2 3 | request := Http.options("http://www.qitasc.com") .build() response := Http.executeHttpRequest(request) |
HTTP Response ¶
HTTP Request Builder methods must have an associated HTTP response. When using executeHttpRequest
, intaQt will always open a new client. To send multuple requests, Http.newClient()
can be used instead.
Syntax
1 | <response HttpResponse> := Http.executeHttpRequest(<request HttpUriRequest>) |
Returns
The response from the server to the message.
Parameter
- request - The HTTP request built using the Request Builder
Example
1 2 3 | request := Http.head("http://www.qitasc.com") .build() response := Http.executeHttpRequest(request) |
Additional Response Builder Methods¶
The following methods can be used on the HttpResponse
received from Http.executeHttpRequest()
. These must be prepended with the response object's name. For example, response.getEntity()
.
Additionally, .getValue()
and .getName()
can be chained to any method involving headers, such as getFirstHeader()
.
Example
1 | locationUrl := response.getFirstHeader("Location").getValue() |
Write to File ¶
Writes the HTTP response to a specified file.
Syntax
1 | <response HttpResonse>.writeToFile(<file File>) |
Parameters
-
response - The HTTP response
-
file - The file being written to
Example
1 2 | response := Http.executeHttpRequest(request) response.writeToFile(File.fromProject("response.txt")) |
Get Status Line ¶
Returns the response's status line, for example, HTTP/1.1 200 OK
.
Additionally, .getProtocolVersion()
, .getReasonPhrase()
and .getStatusCode()
can be chained to getStatusLine()
.
Syntax
1 | <statusLine StatusLine> := <response HttpResonse>.getStatusLine() |
Returns
The response's status line, or null
if not yet set.
Parameter
- response - The HTTP response
Example
1 2 3 4 5 6 7 8 9 10 11 | stepdef "print http content" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(Http.getContentString(response)) println(response.getStatusLine()) statusLine := response.getStatusLine().toString() if not statusLine.contains("200 OK") then assert false ! "error, status code != 200 (OK)" end end |
Get Entity ¶
Returns the response's message entity.
Syntax
1 | <entity MessageEntity> := <response HttpResonse>.getEntity() |
Returns
The message entity, or null
if none.
Parameter
- response - The HTTP response
Example
1 2 3 4 5 6 7 | stepdef "get entity" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.getEntity()) httpEntity := response.getEntity() end |
Get Protocol Version ¶
Returns the protocol version compatible with the response's message.
Syntax
1 | <result ProtocolVersion> := <response HttpResonse>.getProtocolVersion() |
Returns
The protocol version.
Parameters
- response - The HTTP response
Example
1 2 3 4 5 6 7 | stepdef "get protocol version" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.getProtocolVersion()) httpEntity := response.getProtocolVersion() end |
Contains Header ¶
Checks if the specified header is present in the response message.
Syntax
1 | <containsHeader Boolean> := <response HttpResonse>.containsHeader(<headerName String>) |
Returns
true
if at least one header with the specified name is present, false
otherwise.
Parameters
-
response - The HTTP response
-
headerName - The header name to check for
Example
1 2 3 | if (response.containsHeader("Table of Contents")) then println("the response contains a table of contents") end |
Get Headers¶
Returns all specified headers.
Syntax
1 | <result Headers> := <response HttpResonse>.getHeaders(<headerName String>) |
Returns
The specified headers.
Parameters
-
response - The HTTP response
-
headerName - The header name(s) to return
Example
1 2 3 4 5 6 7 | stepdef "get headers" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.getHeaders("Table of Contents")) httpHeaders := response.getHeaders("Table of Contents") end |
Get First Header¶
Returns the first header whose name matches the specified name.
1 | <result Header> := <response HttpResonse>.getFirstHeader(<headerName String>) |
Returns
The first header that matches the specified name, or null
if no match exists.
Parameters
-
response - The HTTP response
-
headerName - The name of header to match
Example
1 2 3 4 5 6 7 | stepdef "get first header" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.getFirstHeader("Table of Contents")) httpFirstHeader := response.getFirstHeader("Table of Contents") end |
Get Last Header¶
Returns the last header whose name property matches the specified name.
Syntax
1 | <result Header> := <response HttpResonse>.getLastHeader(<headerName String>) |
Returns
The last header that matches the specified name, or null
if no match exists.
Parameters
-
response - The HTTP response
-
headerName - The name of header to match
Example
1 2 3 4 5 6 7 | stepdef "get last header" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.getLastHeader("Table of Contents")) httpLastHeader := response.getLastHeader("Table of Contents") end |
Get All Headers¶
Returns all headers.
Syntax
1 | <result Headers> := <response HttpResonse>.getAllHeaders() |
Returns
An array of all the headers contained in the response.
Parameter
- response - The HTTP response
Example
1 2 3 4 5 6 7 8 9 10 | stepdef "get all headers" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.getAllHeaders()) httpAllHeaders := response.getAllHeaders() for header in httpAllHeaders println(header) end end |
Header Iterator¶
Returns an iterator of all header objects in the sequence that they are sent over a connection.
Syntax
1 | <result Iterator> := <response HttpResonse>.headerIterator(<headerName String>) |
Returns
The header iterator.
Parameters
-
response - The HTTP response
-
headerName (Optional) - The name of the headers to iterate over
Example
1 2 3 4 5 6 7 | stepdef "create header iterator" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(response.headerIterator()) httpIterator := response.headerIterator() end |
Get Content String ¶
Returns a string containing the response's message content.
Syntax
1 | <result String> := Http.getContentString(<response HttpResponse>) |
Returns
The content string.
Parameter
- response - The response message whose content will be accessed
Example
1 2 3 4 5 6 | stepdef "print http content" request := Http.post("http://httpbin.org/post") .build() response := Http.executeHttpRequest(request) println(Http.getContentString(response)) end |
Use Case with HTTP and JSON Built-ins
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | stepdef "get the country code of ip {}" /ip/ countryCode := GeoPluginJSON.getCountryCodeOf(ip) setContextObject("countryCode", countryCode) end model GeoPluginJSON func getCountryCodeOf(ipaddress) request := Http.get("http://www.geoplugin.net/json.gp?ip=" + ipaddress).build() response := Http.executeHttpRequest(request) content := response.getContentString() countryCode := extractCountryCodeFromJSON(content) println("Country Code of " + ipaddress + ": " + countryCode) return countryCode end func extractCountryCodeFromJSON(json) decoded := Json.decode(json) return decoded["geoplugin_countryCode"] end end |
In the example above, HTTP Built-ins are used with JSON Built-ins to retrieve information from a JSON file hosted on a web server. The getContentString
function is then used to return the content contained in the response.
String Entity ¶
Creates a StringEntity
, which is the raw data sent in the request. This can then be parsed by the server, which then generates a response.
Syntax
1 | <result StringEntity> := Http.stringEntity(<content String>, <charset String>) |
Returns
The string entity.
Parameters
-
content - The content to be included in the string entity
-
charset (Optional) - The content's charset
Example
1 2 3 4 5 6 7 8 | stepdef "post string to httpbin service" body := Http.stringEntity("Hello world", "UTF-8") request := Http.post("http://httpbin.org/post") .setEntity(body) .build() response := Http.executeHttpRequest(request) println(response.getContentString()) end |
URL Encoded Form Entity Builder ¶
This method returns a FormEntityBuilder
object that can be used to produce a UrlEncodedFormEntity
object. The theUrlEncodedFormEntity
can then be set as a request's entity.
Syntax
1 2 3 4 5 | <formEntityBuilder FormEntityBuilder> := Http.urlEncodedFormEntityBuilder() <formEntity UrlEncodedFormEntity> := <formEntityBuilder FormEntityBuilder> .addParameter(<parameter String>...) .setCharset(<charset String>) .build() |
Returns
The new FormEntityBuilder
and its UrlEncodedFormEntity
.
Parameters
-
parameter - The parameter(s) added to the
FormEntityBuilder
-
setCharset - The form's charset
Example
1 2 3 4 5 6 7 8 9 10 11 | stepdef "print http content" entity := Http.urlEncodedFormEntityBuilder() .addParameter("Name", "Value") .setCharset("UTF-8") .build() request := Http.post("http://httpbin.org/post") .setEntity(entity) .build() response := Http.executeHttpRequest(request) println(response.getEntity()) end |
Multi Part Entity Builder ¶
This method returns a MultipartEntityBuilder
. They may be chained with any non-static multipartEntityBuilder
methods as described in the Apache documentation.
Syntax
1 | <multipartEntity MultipartEntity> := Http.multipartEntityBuilder() |
Returns
The MultipartEntity
. Using this builder one of the following can be called:
-
build() - Returns an
HttpEntity
-
buildEntity() - Returns a
MultipartFormEntity
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | stepdef "http multipart" multipartEntity := Http.multipartEntityBuilder() .addBinaryBody("NAME1", file("/Users/YourName/Desktop/logo.jpg")) .addTextBody("NAME2", "TEST2") .build() request := Http.post("http://yourbrowser.com/post.php") .addHeader("my", "header") .setEntity(multipartEntity) .build() response := Http.executeHttpRequest(request) println( Http .getContentString(response) ) end |
Parsing HTML using XPath¶
The evaluateXPathToString
and evaluateXPathToList
functions return HTML elements as strings or lists. Both HTTP parsing Built-in functions provide return values where HTML escape characters are converted. For example, &lt;
is converted to <
.
Evaluate XPath to String ¶
The evaluateXPathToString
function returns the HTML element located at the XPath as a string.
Synatx
1 | <result Any> := Http.evaluateXPathToString(<xpath String>, <html String>) |
Returns
The HTML element.
Parameters
-
xpath - The XPath to be evaluated
-
html - The XPath's HTML
Example
1 2 3 | result := Http.evaluateXPathToString("/html/body/div", "<html><body><div>HELLO</div></body></html>") assert result = "HELLO" |
Evaluate XPath to List ¶
The evaluateXPathToList
function returns the HTML elements located at the XPath as a list.
Syntax
1 | <result List<Any>> := Http.evaluateXPathToList(<xpath String>, <html String>) |
Returns
The list of XPath elements.
Parameters
-
xpath - The XPath element
-
html - The XPath's
Example
1 | result := Http.evaluateXPathToList("/html/body/div[2]/div", htmlString) |
URL Encode ¶
This function creates URL-encoded strings.
Syntax
1 | <encodedString String> := Http.urlEncode(<text String>) |
Returns
The URL-encoded representation of the text input.
Parameter * input - The text to be encoded
Example
1 2 3 | encoded := Http.urlEncode(" #Test") // prints +%23Test println(encoded) |