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
}

Executing Requests

get

Execute a GET request and return a HyperResponse.

Return: HyperResponse

getAsync

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

Return: Future<HyperResponse>

post

Execute a POST request and return a HyperResponse.

Return: HyperResponse

postAsync

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

Return: Future<HyperResponse>

put

Execute a PUT request and return a HyperResponse.

Return: HyperResponse

putAsync

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

Return: Future<HyperResponse>

patch

Execute a PATCH request and return a HyperResponse.

Return: HyperResponse

patchAsync

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

Return: Future<HyperResponse>

delete

Execute a DELETE request and return a HyperResponse.

Return: HyperResponse

deleteAsync

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

Return: Future<HyperResponse>

Execute a HEAD request and return a HyperResponse.

Return: HyperResponse

headAsync

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

Return: Future<HyperResponse>

options

Execute an OPTIONS request and return a HyperResponse.

Return: HyperResponse

optionsAsync

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

Return: Future<HyperResponse>

send

Send the HTTP request and return a HyperResponse.

Return: HyperResponse

sendAsync

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

Return: Future<HyperResponse>

Building Requests

getRequestId

Gets the unique request ID representing this request.

Return: String

getFullURL

Gets the full URL for the request.

Return: String

getBaseURL

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

Return: String

setBaseURL

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

Return: HyperRequest

getURL

Gets the URL for the request.

Return: String

setURL

Sets the URL for the request.

Return: HyperRequest

setResolveURL

Sets the resolveURL parameter for the request.

Return: HyperRequest

getMethod

Gets the HTTP method for the request.

Return: String

setMethod

Sets the HTTP method for the request.

Return: HyperRequest

withBasicAuth

Sets the username and password for HTTP Basic Auth.

Return: HyperRequest

withCertificateAuth

Sets the username and password for HTTP Basic Auth.

Return: HyperRequest

withNTLMAuth

Sets the username, password, domain and workstation for 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.

Return: HyperRequest

withResponseCallback

Schedules a callback to be ran when receiving the response.

Return: HyperRequest

getUsername

Gets the username for the request.

Return: String

setUsername

Sets the username for the request.

Return: HyperRequest

getPassword

Gets the password for the request.

Return: String

setPassword

Sets the password for the request.

Return: HyperRequest

getTimeout

Gets the timeout for the request, in seconds.

Return: numeric

setTimeout

Sets the timeout for the request, in seconds.

Return: HyperRequest

withoutRedirecting

A convenience method to not follow any redirects.

Return: HyperRequest

withoutEncodingUrl

A convenience method to not encode the url.

WARNING: Not supported on Adobe engines.

Return: HyperRequest

getMaximumRedirects

Gets the maximum number of redirects to follow.

Return: numeric | String

setMaximumRedirects

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

Return: HyperRequest

getBody

Gets the body for the request.

Return: any

setBody

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

Return: HyperRequest

hasBody

Checks if the request has a body.

Return: boolean

getBodyFormat

Gets the body format for the request.

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.

Return: HyperRequest

asJson

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

Return: HyperRequest

asFormFields

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

Return: HyperRequest

asXML

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

Return: HyperRequest

getReferrer

Gets the referrer for the request, if any.

Return: String

getHeaders

Gets the headers for the request.

Return: java.util.LinkedHashMap

setHeaders

Sets the headers for the request.

Return: HyperRequest

setHeader

Set a header for the request.

Return: HyperRequest

withHeaders

Add additional headers 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.

Return: HyperRequest

hasHeader

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

Return: boolean

setContentType

A convenience method to set the Content-Type header.

Return: HyperRequest

setAccept

A convenience method to set the Accept header.

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.

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.

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.

Return: any

getQueryParamByName

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

Return: any

getAllQueryParamsByName

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

Return: array<any>

setQueryParam

Set a query parameter for the request.

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

Return: HyperRequest

appendQueryParam

Append a query parameter for the request.

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.

Return: HyperRequest

appendQueryParams

Appends additional query parameters to the request.

Return: HyperRequest

hasQueryParam

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

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.

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.

Return: HyperRequest

throwErrors

A convenience method to throw on errors.

Return: HyperRequest

allowErrors

A convenience method to not throw on errors.

Return: HyperRequest

clone

Clones the current request into a new HyperRequest.

Return: A new HyperRequest instance cloned from this one.

clear

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

Return: HyperRequest

when

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

Return: HyperRequest

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.

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).

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.

Return: HyperRequest

setAsyncManager

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

Return: HyperRequest

getMemento

Returns a struct representing this HyperRequest.

Return:

{
    "requestID"          : getRequestID(),
    "baseUrl"            : getBaseUrl(),
    "url"                : getUrl(),
    "fullUrl"            : getFullUrl(),
    "method"             : getMethod(),
    "queryParams"        : getQueryParams(),
    "headers"            : getHeaders(),
    "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()
};

debug

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

Throws: NoUrlException when no URL is set.

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

Last updated