AsyncResponse (Beta)

Beta Feature

The ability to make asynchronous HTTP requests is currently available as a beta development feature.

All beta asynchronous HTTP APIs exist in the asynchttp_v1 namespace. Approximately 30 days after the launch of this beta feature, we will evaluate metrics and your feedback, and make adjustments as necessary.

When released generally, it is likely that the v1 postfix will be dropped, and a deprecation period will be announced to change existing usages accordingly.

If, for unexpected reasons, usage of asynchronous HTTP requests has negative impacts on the SmartThings platform, SmartThings reserves the right to alter or remove any impacted asynchronous HTTP APIs without notice. This is highly unlikely and every effort will be made to avoid such a scenario.

If you experience issues or have feedback on these asynchronous HTTP APIs, please share them on this community thread.

The AsyncResponse object represents the response of an asynchronous HTTP request. An instance of it is passed to the response handler specified when making the request.

This documentation is specific to handling responses from asynchronous HTTP requests. For reference documentation regarding making the request, see the Async HTTP API (Beta) documentation.


getData()

Return the response as a string. Throws an exception if the request failed to get a response (e.g. Connection timeout, Response timeout), or if the status code was not 2XX.

Signature:
String getData()

Example:

def responseHandler(response, data) {
    log.debug "raw response: $response.data"
}

getErrorData()

In the Event of an error response, returns the response body as a string. Throws an exception if the response is successful and has a 2XX response.

Signature:
String getErrorData()

Example:

def responseHandler(response, data) {
    if (response.hasError()) {
        log.debug "raw response: $response.errorData"
    }
}

getErrorJson()

If the response has an error, parses the response body as JSON and returns the corresponding data structure. Throws an exception if the response is successful and has a 2XX response, or if the body fails to parse as JSON.

Signature:
JSONElement getErrorJson()

Example:

def responseHandler(response, data) {
    if (response.hasError()) {
        try {
            log.debug "error json: $response.errorJson"
        } catch (e) {
            log.debug "error parsing json - raw error data is $response.errorData"
        }
    }
}

getErrorMessage()

Gets a human-readable error message if the request failed to get a response (e.g. Connection timeout, Response timeout), or if the status code was not 2XX.

Signature:
String getErrorMessage()

Example:

def responseHandler(response, data) {
    if (response.hasError()) {
        log.debug "error on response: $response.errorMessage"
    }
}

getErrorXml()

If the response has an error, parses the response body as XML and returns the corresponding data structure. Throws an exception if the response is successful and has a 2XX response, or if the body fails to parse as XML.

Note

You can learn more about Groovy XML parsing and GPath here.

Signature:
GPathResult getErrorXml()

Example:

def responseHandler(response, data) {
    if (response.hasError()) {
        try {
            def xml = response.errorXml
        } catch(e) {
            log.warn "could not parse body to XML"
        }
    }
}

getHeaders()

Get the headers of the response.

Signature:
Map<String, String> getHeaders()
Returns:
Map < String , String > - A map of response headers keyed by the header name.

Example:

def responseHandler(response, data) {
    def headers = response.headers
    headers.each {header, value ->
        log.debug "$header: $value"
    }
}

getJson()

Parses the response body as JSON and returns the corresponding data structure. Throws an exception if the body fails to parse as JSON, if the request failed to get a response (e.g. Connection timeout, Response timeout), or if the status code was not 2XX).

Signature:
JSONElement getJson()

Example:

include 'asynchttp_v1'

def initialize() {
    def params = [
        uri: 'https://someapi.com',
        path: '/some/path',
        requestContentType: 'application/json'
    ]
    asynchttp_v1.get(processResponse, params)
}

def processResponse(response, data) {
    try {
        log.debug "json response is: $response.json"
    } catch (e) {
        log.error("exception during response processing", e)
    }

}

getStatus()

Get the status code of the response.

Signature:
int getStatus()

Example:

def responseHandler(response, data) {
    log.debug "response status code is: $response.status"
}

getWarningMessages()

Gets a list of warning messages, if applicable. Returns an empty list if there are no warning messages.

Typically used for debugging purposes. For example, a warning message will be found if the response is larger than the allowable limit.

Signature:
List<String> getWarningMessages()

Example:

def responseHandler(response, data) {
    log.debug "warning messages: $response.warningMessages"
}

getXml()

Parses the response body as XML and returns the corresponding data structure. Throws an exception if the body fails to parse as XML, if the request failed to get a response (e.g. Connection timeout, Response timeout), or if the status code was not 2XX).

Note

You can learn more about Groovy XML parsing and GPath here.

Signature:
GPathResult getXml()

Example:

def responseHandler(response, data) {
    if (!response.hasError()) {
        try {
            def xml = response.xml
        } catch(e) {
            log.warn "could not parse body to XML"
        }
    }
}

hasError()

Return if the request has an error of some sort. This will be true if the request failed to complete or returned a non-2XX status code, and false if the request succeeded with a 2XX status code.

Signature:
boolean hasError()

Example:

def responseHandler(response, data) {
    if (response.hasError()) {
        log.error "response has error: ${response.getErrorMessage()}"
    }
}