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.
Defaults
The following are default properties for a HyperRequest
:
Executing Requests
get
get
Execute a GET
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
getAsync
Execute a GET
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
post
Execute a POST
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
postAsync
Execute a POST
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
put
Execute a PUT
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
putAsync
Execute a PUT
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
patch
Execute a PATCH
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
patchAsync
Execute a PATCH
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
delete
Execute a DELETE
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
deleteAsync
Execute a DELETE
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
>
head
head
Execute a HEAD
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
headAsync
Execute a HEAD
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
options
Execute an OPTIONS
request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
optionsAsync
Execute an OPTIONS
request asynchronously. Returns a ColdBox Future that returns a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
Send the HTTP request and return a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperResponse
sendAsync
sendAsync
Send the HTTP request asynchronously and return a ColdBox Future that will resolve to a HyperResponse
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: Future
<
HyperResponse
>
Building Requests
getRequestId
getRequestId
Gets the unique request ID representing this request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
getFullURL
getFullURL
Gets the full URL for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
withQueryString | boolean | false | false | Includes the configured query string with the full URL |
Return: String
getBaseURL
getBaseURL
Gets the base URL for the request. The base URL is combined with the URL when making the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
setBaseURL
setBaseURL
Sets the base URL for the request. The base URL is combined with the URL when making the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | string | true | The base URL for the request, e.g. |
Return: HyperRequest
getURL
getURL
Gets the URL for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
setURL
setURL
Sets the URL for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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. |
Return: HyperRequest
setResolveURL
setResolveURL
Sets the resolveURL parameter for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | boolean | false | false | Resolves URLs in the response body to absolute URLs, including the port number |
Return: HyperRequest
getMethod
getMethod
Gets the HTTP method for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
setMethod
setMethod
Sets the HTTP method for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | string | true | The HTTP method for the request. |
Return: HyperRequest
withBasicAuth
withBasicAuth
Sets the username and password for HTTP Basic Auth.
Name | Type | Required | Default | Description |
---|---|---|---|---|
username | string | true | The username for the basic auth. | |
password | string | true | The password for the basic auth. |
Return: HyperRequest
withCertificateAuth
withCertificateAuth
Sets the username and password for HTTP Basic Auth.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
withNTLMAuth
Sets the username, password, domain and workstation for NTLM Auth.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
withRequestCallback
Schedules a callback to be ran when executing the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
callback | function | true | The callback to run when executing the request. |
Return: HyperRequest
withResponseCallback
withResponseCallback
Schedules a callback to be ran when receiving the response.
Name | Type | Required | Default | Description |
---|---|---|---|---|
callback | function | true | The callback to run when receiving the response. |
Return: HyperRequest
getUsername
getUsername
Gets the username for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
setUsername
setUsername
Sets the username for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | string | true | The username for the request. |
Return: HyperRequest
getPassword
getPassword
Gets the password for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
setPassword
setPassword
Sets the password for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | string | true | The password for the request. |
Return: HyperRequest
getTimeout
getTimeout
Gets the timeout for the request, in seconds.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: numeric
setTimeout
setTimeout
Sets the timeout for the request, in seconds.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | string | true | The timeout for the request, in seconds. |
Return: HyperRequest
withoutRedirecting
withoutRedirecting
A convenience method to not follow any redirects.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
withoutEncodingUrl
withoutEncodingUrl
A convenience method to not encode the url.
WARNING: Not supported on Adobe engines.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
getMaximumRedirects
getMaximumRedirects
Gets the maximum number of redirects to follow.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: numeric | String
setMaximumRedirects
setMaximumRedirects
Sets the maximum number of redirects to follow. A value of *
will follow redirects infinitely.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | any | true | The maximum number of redirects to follow. |
Return: HyperRequest
getBody
getBody
Gets the body for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: any
setBody
setBody
Sets the body for the request. Complex values will be serialized before sending the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | any | true | The body for the request. |
Return: HyperRequest
hasBody
hasBody
Checks if the request has a body.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: boolean
getBodyFormat
getBodyFormat
Gets the body format for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
setBodyFormat
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | any | true | The body format for the request. |
Return: HyperRequest
asJson
asJson
A convenience method to set the body format and Content-Type to json
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
asFormFields
asFormFields
A convenience method to set the body format and Content-Type to form fields.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
asXML
asXML
A convenience method to set the body format and Content-Type to xml
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
asBinary
asBinary
A convenience method to set the body format to binary
and Content-Type to application/octet-stream
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
getReferrer
getReferrer
Gets the referrer for the request, if any.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: String
getHeaders
getHeaders
Gets the headers for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: java.util.LinkedHashMap
setHeaders
setHeaders
Sets the headers for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | struct | true | The headers for the request. |
Return: HyperRequest
setHeader
setHeader
Set a header for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the header. | |
value | string | true | The value of the header. |
Return: HyperRequest
withHeaders
withHeaders
Add additional headers to the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
headers | struct | true | A struct of headers to add to the request. |
Return: HyperRequest
forwardHeaders
forwardHeaders
Adds specified headers to the request if they exist. Usually used in conjunction with the current CFML request headers.
Name | Type | Required | Default | Description |
---|---|---|---|---|
names | array | true | An array of header names to add to the request if they exist in the | |
headers | struct | false |
| A struct of headers to inspect. |
Return: HyperRequest
hasHeader
hasHeader
Check if the request has a header with the given name.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the header to check. |
Return: boolean
getCookies
getCookies
Gets the cookies for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: struct<ordered>
setCookies
setCookies
Sets the cookies for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | struct | true | The headers for the request. |
Return: HyperRequest
setCookie
setCookie
Set a cookie for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the header. | |
value | string | true | The value of the header. |
Return: HyperRequest
withCookies
withCookies
Add additional cookies to the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
cookies | struct | true | A struct of headers to add to the request. |
Return: HyperRequest
withCredentials
withCredentials
Sends all current cookies along with the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
hasCookie
hasCookie
Check if the request has a cookie with the given name.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the header to check. |
Return: boolean
setUserAgent
setUserAgent
A convenience method to set the User-Agent
header.
Name | Type | Required | Default | Description |
---|---|---|---|---|
userAgent | string | true | The User-Agent value for the request |
Return: HyperRequest
setContentType
setContentType
A convenience method to set the Content-Type
header.
Name | Type | Required | Default | Description |
---|---|---|---|---|
type | string | true | The Content-Type value for the request |
Return: HyperRequest
setAccept
setAccept
A convenience method to set the Accept
header.
Name | Type | Required | Default | Description |
---|---|---|---|---|
type | string | true | The Accept value for the request |
Return: HyperRequest
getQueryParams
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: array<struct<string, any>>
setQueryParams
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
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | array | true | The query parameters for the as an array of param structs. |
Return: HyperRequest
getQueryParam
getQueryParam
DEPRECATED: Use getQueryParamByName
Gets the first value for a certain query parameter. Returns an empty string if the query parameter does not exist.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the query parameter to retrieve the first value. |
Return: any
getQueryParamByName
getQueryParamByName
Gets the first value for a certian query parameter. Returns an empty string if the query parameter does not exist.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the query parameter to retrieve the first value. |
Return: any
getAllQueryParamsByName
getAllQueryParamsByName
Get all the values for a certain query parameter. Returns an empty array if the query parameter does not exist.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the query parameter to retrieve all of its values. |
Return: array<any>
setQueryParam
setQueryParam
Set a query parameter for the request.
Note: This removes all other query params with the same name.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the query parameter. | |
value | string | true | The value of the query parameter. |
Return: HyperRequest
appendQueryParam
appendQueryParam
Append a query parameter for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the query parameter. | |
value | string | true | The value of the query parameter. |
Return: HyperRequest
withQueryParams
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
queryParams | struct | true | A struct of query parameters to add to the request. |
Return: HyperRequest
appendQueryParams
appendQueryParams
Appends additional query parameters to the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
queryParams | struct | true | A struct of query parameters to add to the request. |
Return: HyperRequest
hasQueryParam
hasQueryParam
Check if the request has a query parameter with the given name.
Name | Type | Required | Default | Description |
---|---|---|---|---|
name | string | true | The name of the query parameter to check. |
Return: boolean
attach
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
value | boolean | true | The value of the throw on error flag. |
Return: HyperRequest
throwErrors
throwErrors
A convenience method to throw on errors.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
allowErrors
allowErrors
A convenience method to not throw on errors.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
clone
clone
Clones the current request into a new HyperRequest.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: A new HyperRequest
instance cloned from this one.
clear
clear
Clears the request of any set values, including defaults passed by the builder.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: HyperRequest
when
when
Helper to conditionally execute a callback for the HyperRequest
. This method lets you use conditionals without breaking chaining.
Name | Type | Required | Default | Description |
---|---|---|---|---|
condition |
|
| The condition to check. | |
successCallback |
|
| The callback to execute if the condition is true. The callback is passed the | |
failureCallback |
|
|
| The callback to execute if the condition is false. The callback is passed the |
Return: HyperRequest
retry
retry
Configures the request to retry failed requests.
Name | Type | Required | Default | Description |
---|---|---|---|---|
attempts |
|
| 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 |
|
| The delay to use for each of the | |
predicate |
|
| 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 |
Return: HyperRequest
getRetries
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: array<numeric>
getCurrentRequestCount
getCurrentRequestCount
Returns the current request count. Defaults to 1
. The only time this will increase is if retries
have been configured for the request.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: numeric
getRetryPredicate
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: numeric
setProperties
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
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
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
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).
Name | Type | Required | Default | Description |
---|---|---|---|---|
httpClient |
|
| The httpClient to use for the request. |
Return: HyperRequest
setInterceptorService
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.
Name | Type | Required | Default | Description |
---|---|---|---|---|
interceptorService | any |
| The interceptor service to use for the request. |
Return: HyperRequest
setAsyncManager
setAsyncManager
Sets the ColdBox AsyncManager to send requests asynchronously. A noop option is provided in the init
for non-ColdBox usage.
Name | Type | Required | Default | Description |
---|---|---|---|---|
asyncManager | any |
| The asyncManager to use for the request. |
Return: HyperRequest
getMemento
getMemento
Returns a struct representing this HyperRequest
.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return:
debug
debug
Creates a debug representation of the HTTP request for the current HTTP client.
Throws: NoUrlException
when no URL is set.
Name | Type | Required | Default | Description |
---|---|---|---|---|
No arguments |
Return: Dependent on the configured HTTP Client. See specific HTTP Client documentation for details.