HyperRequest

Though the HyperBuilder is the component you will most likely inject, HyperRequest is the component will you interact with the most. HyperRequest provides a fluent interface to configure your HTTP call.

hyper.get( "https//api.github.com/users" );

hyper.setMethod( "PUT" )
    .withHeaders( { "Authorization" = "Bearer #token#" } )
    .setUrl( "https://jsonplaceholder.typicode.com/posts/1" )
    .setBody( {
        title: "New Title"
    } )
    .send();

Defaults

The following are default properties for a HyperRequest:

{
    "method": "GET"
    "resolveUrls": false,
    "encodeUrl": true,
    "timeout": 10, // in seconds
    "maximumRedirects": "*", // follow redirects indefinitely
    "bodyFormat": "json",
    "throwOnError": false,
    "headers": { "User-Agent": "HyperCFML/#versionNumber#" }
}

Executing Requests

get

Execute a GET request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

queryParams

struct

false

null

An optional struct of query parameters to set for the request.

Return: HyperResponse

getAsync

Execute a GET request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

queryParams

struct

false

null

An optional struct of query parameters to set for the request.

Return: Future<HyperResponse>

post

Execute a POST request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: HyperResponse

postAsync

Execute a POST request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: Future<HyperResponse>

put

Execute a PUT request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: HyperResponse

putAsync

Execute a PUT request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: Future<HyperResponse>

patch

Execute a PATCH request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: HyperResponse

patchAsync

Execute a PATCH request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: Future<HyperResponse>

delete

Execute a DELETE request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: HyperResponse

deleteAsync

Execute a DELETE request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

body

struct

false

null

An optional body to set for the request.

Return: Future<HyperResponse>

Execute a HEAD request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

queryParams

struct

false

null

An optional struct of query parameters to set for the request.

Return: HyperResponse

headAsync

Execute a HEAD request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

queryParams

struct

false

null

An optional struct of query parameters to set for the request.

Return: Future<HyperResponse>

options

Execute an OPTIONS request and return a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

queryParams

struct

false

null

An optional struct of query parameters to set for the request.

Return: HyperResponse

optionsAsync

Execute an OPTIONS request asynchronously. Returns a ColdBox Future that returns a HyperResponse.

NameTypeRequiredDefaultDescription

url

string

false

null

An optional URL to set for the request.

queryParams

struct

false

null

An optional struct of query parameters to set for the request.

Return: Future<HyperResponse>

send

Send the HTTP request and return a HyperResponse.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperResponse

sendAsync

Send the HTTP request asynchronously and return a ColdBox Future that will resolve to a HyperResponse.

NameTypeRequiredDefaultDescription

No arguments

Return: Future<HyperResponse>

Building Requests

getRequestId

Gets the unique request ID representing this request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

getFullURL

Gets the full URL for the request.

NameTypeRequiredDefaultDescription

withQueryString

boolean

false

false

Includes the configured query string with the full URL

Return: String

getBaseURL

Gets the base URL for the request. The base URL is combined with the URL when making the request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

setBaseURL

Sets the base URL for the request. The base URL is combined with the URL when making the request.

NameTypeRequiredDefaultDescription

value

string

true

The base URL for the request, e.g. https://api.github.com/.

Return: HyperRequest

getURL

Gets the URL for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

setURL

Sets the URL for the request.

NameTypeRequiredDefaultDescription

value

string

true

The URL for the request. It can either be a full url or a URI resource for use with the baseURL. e.g. /repos.

Return: HyperRequest

setResolveURL

Sets the resolveURL parameter for the request.

NameTypeRequiredDefaultDescription

value

boolean

false

false

Resolves URLs in the response body to absolute URLs, including the port number

Return: HyperRequest

getMethod

Gets the HTTP method for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

setMethod

Sets the HTTP method for the request.

NameTypeRequiredDefaultDescription

value

string

true

The HTTP method for the request.

Return: HyperRequest

withBasicAuth

Sets the username and password for HTTP Basic Auth.

NameTypeRequiredDefaultDescription

username

string

true

The username for the basic auth.

password

string

true

The password for the basic auth.

Return: HyperRequest

withCertificateAuth

Sets the username and password for HTTP Basic Auth.

NameTypeRequiredDefaultDescription

certificatePath

string

true

The mapped path to the certificate used to authenticate.

password

string

false

The optional password used to decrypt the certificate.

Return: HyperRequest

withNTLMAuth

Sets the username, password, domain and workstation for NTLM Auth.

NameTypeRequiredDefaultDescription

username

string

true

The username for the NTLM auth.

password

string

true

The password for the NTLM auth.

domain

string

true

The domain for the NTLM auth.

workstation

string

true

The workstation for the NTLM auth.

Workstation can be obtained with createObject('java','java.net.InetAddress').getLocalHost().getHostName()

Return: HyperRequest

withRequestCallback

Schedules a callback to be ran when executing the request.

NameTypeRequiredDefaultDescription

callback

function

true

The callback to run when executing the request.

Return: HyperRequest

withResponseCallback

Schedules a callback to be ran when receiving the response.

NameTypeRequiredDefaultDescription

callback

function

true

The callback to run when receiving the response.

Return: HyperRequest

getUsername

Gets the username for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

setUsername

Sets the username for the request.

NameTypeRequiredDefaultDescription

value

string

true

The username for the request.

Return: HyperRequest

getPassword

Gets the password for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

setPassword

Sets the password for the request.

NameTypeRequiredDefaultDescription

value

string

true

The password for the request.

Return: HyperRequest

getTimeout

Gets the timeout for the request, in seconds.

NameTypeRequiredDefaultDescription

No arguments

Return: numeric

setTimeout

Sets the timeout for the request, in seconds.

NameTypeRequiredDefaultDescription

value

string

true

The timeout for the request, in seconds.

Return: HyperRequest

withoutRedirecting

A convenience method to not follow any redirects.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

withoutEncodingUrl

A convenience method to not encode the url.

WARNING: Not supported on Adobe engines.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

getMaximumRedirects

Gets the maximum number of redirects to follow.

NameTypeRequiredDefaultDescription

No arguments

Return: numeric | String

setMaximumRedirects

Sets the maximum number of redirects to follow. A value of * will follow redirects infinitely.

NameTypeRequiredDefaultDescription

value

any

true

The maximum number of redirects to follow.

Return: HyperRequest

getBody

Gets the body for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: any

setBody

Sets the body for the request. Complex values will be serialized before sending the request.

NameTypeRequiredDefaultDescription

value

any

true

The body for the request.

Return: HyperRequest

hasBody

Checks if the request has a body.

NameTypeRequiredDefaultDescription

No arguments

Return: boolean

getBodyFormat

Gets the body format for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: String

setBodyFormat

Sets the body format for the request. Recognized values are formFields, json, or xml. It is highly recommended to use asFormFields, asJson, or asXML instead. If you set this value to a non-recognized value, the body will be passed along as-is to the body of the HTTP request.

NameTypeRequiredDefaultDescription

value

any

true

The body format for the request.

Return: HyperRequest

asJson

A convenience method to set the body format and Content-Type to json.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

asFormFields

A convenience method to set the body format and Content-Type to form fields.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

asXML

A convenience method to set the body format and Content-Type to xml.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

asBinary

A convenience method to set the body format to binary and Content-Type to application/octet-stream.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

getReferrer

Gets the referrer for the request, if any.

NameTypeRequiredDefaultDescription

No arguments

Return: String

getHeaders

Gets the headers for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: java.util.LinkedHashMap

setHeaders

Sets the headers for the request.

NameTypeRequiredDefaultDescription

value

struct

true

The headers for the request.

Return: HyperRequest

setHeader

Set a header for the request.

NameTypeRequiredDefaultDescription

name

string

true

The name of the header.

value

string

true

The value of the header.

Return: HyperRequest

withHeaders

Add additional headers to the request.

NameTypeRequiredDefaultDescription

headers

struct

true

A struct of headers to add to the request.

Return: HyperRequest

forwardHeaders

Adds specified headers to the request if they exist. Usually used in conjunction with the current CFML request headers.

NameTypeRequiredDefaultDescription

names

array

true

An array of header names to add to the request if they exist in the headers struct.

headers

struct

false

getHTTPRequestData( false ).headers

A struct of headers to inspect.

Return: HyperRequest

hasHeader

Check if the request has a header with the given name.

NameTypeRequiredDefaultDescription

name

string

true

The name of the header to check.

Return: boolean

getCookies

Gets the cookies for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: struct<ordered>

setCookies

Sets the cookies for the request.

NameTypeRequiredDefaultDescription

value

struct

true

The headers for the request.

Return: HyperRequest

setCookie

Set a cookie for the request.

NameTypeRequiredDefaultDescription

name

string

true

The name of the header.

value

string

true

The value of the header.

Return: HyperRequest

withCookies

Add additional cookies to the request.

NameTypeRequiredDefaultDescription

cookies

struct

true

A struct of headers to add to the request.

Return: HyperRequest

withCredentials

Sends all current cookies along with the request.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

hasCookie

Check if the request has a cookie with the given name.

NameTypeRequiredDefaultDescription

name

string

true

The name of the header to check.

Return: boolean

setUserAgent

A convenience method to set the User-Agent header.

NameTypeRequiredDefaultDescription

userAgent

string

true

The User-Agent value for the request

Return: HyperRequest

setContentType

A convenience method to set the Content-Type header.

NameTypeRequiredDefaultDescription

type

string

true

The Content-Type value for the request

Return: HyperRequest

setAccept

A convenience method to set the Accept header.

NameTypeRequiredDefaultDescription

type

string

true

The Accept value for the request

Return: HyperRequest

getQueryParams

Gets the query parameters for the request.

This method returns an array of param structs that is used under the hood by Hyper. You probably want to use getQueryParamByName or getAllQueryParamsByName instead.

NameTypeRequiredDefaultDescription

No arguments

Return: array<struct<string, any>>

setQueryParams

Sets the query parameters for the request.

This method accepts an array of param structs that is used under the hood by Hyper. You probably want to use withQueryParams or appendQueryParams instead.

If needed, param structs have two keys, name and value.

NameTypeRequiredDefaultDescription

value

array

true

The query parameters for the as an array of param structs.

Return: HyperRequest

getQueryParam

DEPRECATED: Use getQueryParamByName

Gets the first value for a certain query parameter. Returns an empty string if the query parameter does not exist.

NameTypeRequiredDefaultDescription

name

string

true

The name of the query parameter to retrieve the first value.

Return: any

getQueryParamByName

Gets the first value for a certian query parameter. Returns an empty string if the query parameter does not exist.

NameTypeRequiredDefaultDescription

name

string

true

The name of the query parameter to retrieve the first value.

Return: any

getAllQueryParamsByName

Get all the values for a certain query parameter. Returns an empty array if the query parameter does not exist.

NameTypeRequiredDefaultDescription

name

string

true

The name of the query parameter to retrieve all of its values.

Return: array<any>

setQueryParam

Set a query parameter for the request.

Note: This removes all other query params with the same name.

NameTypeRequiredDefaultDescription

name

string

true

The name of the query parameter.

value

string

true

The value of the query parameter.

Return: HyperRequest

appendQueryParam

Append a query parameter for the request.

NameTypeRequiredDefaultDescription

name

string

true

The name of the query parameter.

value

string

true

The value of the query parameter.

Return: HyperRequest

withQueryParams

Add additional query parameters to the request.

Note: This will remove any values with duplicate keys prior to adding the new struct of params.

NameTypeRequiredDefaultDescription

queryParams

struct

true

A struct of query parameters to add to the request.

Return: HyperRequest

appendQueryParams

Appends additional query parameters to the request.

NameTypeRequiredDefaultDescription

queryParams

struct

true

A struct of query parameters to add to the request.

Return: HyperRequest

hasQueryParam

Check if the request has a query parameter with the given name.

NameTypeRequiredDefaultDescription

name

string

true

The name of the query parameter to check.

Return: boolean

attach

Attaches a file to the Hyper request. Also sets the Content-Type as multipart/form-data. Multiple files can be attached by calling attach multiple times before calling a send method.

NameTypeRequiredDefaultDescription

name

string

true

The name of the file being uploaded.

path

string

true

The absolute path to the file to be uploaded.

mimeType

string

false

An optional mime type to associate with the file.

Return: HyperRequest

setThrowOnError

Sets the throw on error property for the request. If true, statuses in the 4xx and 5xx range will be turned in to exceptions.

NameTypeRequiredDefaultDescription

value

boolean

true

The value of the throw on error flag.

Return: HyperRequest

throwErrors

A convenience method to throw on errors.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

allowErrors

A convenience method to not throw on errors.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

clone

Clones the current request into a new HyperRequest.

NameTypeRequiredDefaultDescription

No arguments

Return: A new HyperRequest instance cloned from this one.

clear

Clears the request of any set values, including defaults passed by the builder.

NameTypeRequiredDefaultDescription

No arguments

Return: HyperRequest

when

Helper to conditionally execute a callback for the HyperRequest. This method lets you use conditionals without breaking chaining.

NameTypeRequiredDefaultDescription

condition

boolean

true

The condition to check.

successCallback

function

true

The callback to execute if the condition is true. The callback is passed the HyperRequest instance.

failureCallback

function

false

null

The callback to execute if the condition is false. The callback is passed the HyperRequest instance.

Return: HyperRequest

retry

Configures the request to retry failed requests.

NameTypeRequiredDefaultDescription

attempts

numeric / array<numeric>

true

Either the max number of retry attempts to make or an array containing retry delays between each attempt. If a numeric value is passed in, the delay argument is required.

delay

numeric

false

The delay to use for each of the attempts. This argument is required if attempts is a numeric value. If attempts is an array, this value is ignored.

predicate

function

false

The predicate function to call to determine if a retry should be attempted. This function is only called if there are configured retries available. To retry a request, this function should return true. It is passed the response and request as parameters. Additionally, the request can be modified in this method for the next retry attempt.

Return: HyperRequest

getRetries

Returns the current retry configuration which is an array of delay times. A request that needs to be retried will be retried up to the amount of items in this array. This array can be set using the retry method.

In most cases, you do not need to interact with this method directly. Use the retry method instead.

NameTypeRequiredDefaultDescription

No arguments

Return: array<numeric>

getCurrentRequestCount

Returns the current request count. Defaults to 1. The only time this will increase is if retries have been configured for the request.

NameTypeRequiredDefaultDescription

No arguments

Return: numeric

getRetryPredicate

Returns the current callback function that is called to decide if a request should be retried. This is only called if there are available retries left.

This callback is passed the response and the request as parameters.

A request will be retried if this function returns true.

In this function, the passed in request can be modified for the next retry.

In most cases, you do not need to interact with this method directly. Use the retry method instead.

NameTypeRequiredDefaultDescription

No arguments

Return: numeric

setProperties

Quickly set many request properties using a struct. The key should be the name of one of the properties on the request, e.g. url, headers, method, body.

NameTypeRequiredDefaultDescription

properties

struct

true

A struct of properties to set. Each property name will be set on the request. Properties that don't exist on the request will throw an error.

Return: HyperRequest

setHttpClient

Sets the HTTP Client to use for the request. The client should conform to the HyperHttpClientInterface (though it does not need to use the implements keyword).

NameTypeRequiredDefaultDescription

httpClient

HyperHttpClientInterface

true

The httpClient to use for the request.

Return: HyperRequest

setInterceptorService

Sets the ColdBox Interceptor Service to announce request and response interception points. A noop option is provided in the init for non-ColdBox usage.

NameTypeRequiredDefaultDescription

interceptorService

any

true

The interceptor service to use for the request.

Return: HyperRequest

setAsyncManager

Sets the ColdBox AsyncManager to send requests asynchronously. A noop option is provided in the init for non-ColdBox usage.

NameTypeRequiredDefaultDescription

asyncManager

any

true

The asyncManager to use for the request.

Return: HyperRequest

getMemento

Returns a struct representing this HyperRequest.

NameTypeRequiredDefaultDescription

No arguments

Return:

{
    "requestID"           : getRequestID(),
    "baseUrl"             : getBaseUrl(),
    "url"                 : getUrl(),
    "fullUrl"             : getFullUrl(),
    "method"              : getMethod(),
    "queryParams"         : getQueryParams(),
    "headers"             : getHeaders(),
    "cookies"             : getCookies(),
    "files"               : getFiles(),
    "bodyFormat"          : getBodyFormat(),
    "body"                : getBody(),
    "referrer"            : isNull( variables.referrer ) ? "" : variables.referrer,
    "throwOnError"        : getThrowOnError(),
    "timeout"             : getTimeout(),
    "maximumRedirects"    : getMaximumRedirects(),
    "authType"            : getAuthType(),
    "username"            : getUsername(),
    "password"            : getPassword(),
    "clientCert"          : isNull( variables.clientCert ) ? "" : variables.clientCert,
    "clientCertPassword"  : isNull( variables.clientCertPassword ) ? "" : variables.clientCertPassword,
    "domain"              : getDomain(),
    "workstation"         : getWorkstation(),
    "resolveUrls"         : getResolveUrls(),
    "encodeUrl"           : getEncodeUrl(),
    "retries"             : getRetries(),
    "currentRequestCount" : getCurrentRequestCount()
};

debug

Creates a debug representation of the HTTP request for the current HTTP client.

Throws: NoUrlException when no URL is set.

NameTypeRequiredDefaultDescription

No arguments

Return: Dependent on the configured HTTP Client. See specific HTTP Client documentation for details.