Async HTTP API (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.

All asynchronous HTTP APIs are only availble after including the “asynchttp_v1” API:

include 'asynchttp_v1'

def initialize() {
    // invoke methods on the injected asynchttp_v1 object that was included
    asynchttp_v1.get(...)
}

This documentation is specific to making requests using the Async HTTP API. For reference documentation on working with the response, see the AsyncResponse (Beta) documentation.


delete()

Make a DELETE request which will not block execution and therefore can run longer than the execution timeout.

Signature:
void delete(String callbackMethod, Map params, Map data = null)

Parameters:

String callbackMethod - the name of the method to call with the response.

Map params - parameters for the request. Supported keys below:

Key Description
uri (required) Either a URI or URL of the endpoint to make a request from.
path Request path that is merged with the URI.
query Map of URL query parameters.
headers Map of HTTP headers.
requestContentType The value of the Content-Type request header. Defaults to 'application/json'.
contentType The value of the Accept request header. Defaults to the value of the requestContentType parameter if not specified.
body The request body to send. Can be a string, or if the requestContentType is "application/json", a Map or List (will be serialized to JSON).

Map data (optional) - A map of data to pass to the response handler.

Example:

include 'asynchttp_v1'

def initialize() {
    def params = [
        uri: 'https://someapi.com',
        path: '/some/path',
        body: [key1: 'value 1']
    ]
    asynchttp_v1.delete(processResponse, params)
}

def processResponse(response, data) { ... }

get()

Make a GET request which will not block execution and therefore can run longer than the execution timeout.

Signature:
void get(String callbackMethod, Map params, Map data = null)

Parameters:

String callbackMethod - the name of the method to call with the response.

Map params - parameters for the request. Supported keys below:

Key Description
uri (required) Either a URI or URL of the endpoint to make a request from.
path Request path that is merged with the URI.
query Map of URL query parameters.
headers Map of HTTP headers.
requestContentType The value of the Content-Type request header. Defaults to 'application/json'.
contentType The value of the Accept request header. Defaults to the value of the requestContentType parameter if not specified.

Map data (optional) - A map of data to pass to the response handler.

Example:

include 'asynchttp_v1'

def initialize() {
    def params = [
        uri: 'https://api.github.com',
        path: '/search/code',
        query: [q: "httpGet+repo:SmartThingsCommunity/SmartThingsPublic"],
        contentType: 'application/json'
    ]
    asynchttp_v1.get(processResponse, params)
}

def processResponse(response, data) { ... }

patch()

Make a PATCH request which will not block execution and therefore can run longer than the execution timeout.

Signature:
void patch(String callbackMethod, Map params, Map data = null)

Parameters:

String callbackMethod - the name of the method to call with the response.

Map params - parameters for the request. Supported keys below:

Key Description
uri (required) Either a URI or URL of the endpoint to make a request from.
path Request path that is merged with the URI.
query Map of URL query parameters.
headers Map of HTTP headers.
requestContentType The value of the Content-Type request header. Defaults to 'application/json'.
contentType The value of the Accept request header. Defaults to the value of the requestContentType parameter if not specified.
body The request body to send. Can be a string, or if the requestContentType is "application/json", a Map or List (will be serialized to JSON).

Map data (optional) - A map of data to pass to the response handler.

Example:

include 'asynchttp_v1'

def initialize() {
    def params = [
        uri: 'https://someapi.com',
        path: '/some/path',
        body: [key1: 'value 1']
    ]
    asynchttp_v1.patch(processResponse, params)
}

def processResponse(response, data) { ... }

post()

Make a POST request which will not block execution and therefore can run longer than the execution timeout.

Signature:
void post(String callbackMethod, Map params, Map data = null)

Parameters:

String callbackMethod - the name of the method to call with the response.

Map params - parameters for the request. Supported keys below:

Key Description
uri (required) Either a URI or URL of the endpoint to make a request from.
path Request path that is merged with the URI.
query Map of URL query parameters.
headers Map of HTTP headers.
requestContentType The value of the Content-Type request header. Defaults to 'application/json'.
contentType The value of the Accept request header. Defaults to the value of the requestContentType parameter if not specified.
body The request body to send. Can be a string, or if the requestContentType is "application/json", a Map or List (will be serialized to JSON).

Map data (optional) - A map of data to pass to the response handler.

Example:

include 'asynchttp_v1'

def initialize() {
    def params = [
        uri: 'https://someapi.com',
        path: '/some/path',
        body: [key1: 'value 1']
    ]
    asynchttp_v1.post(processResponse, params)
}

def processResponse(response, data) { ... }

put()

Make a PUT request which will not block execution and therefore can run longer than the execution timeout.

Signature:
void put(String callbackMethod, Map params, Map data = null)

Parameters:

String callbackMethod - the name of the method to call with the response.

Map params - parameters for the request. Supported keys below:

Key Description
uri (required) Either a URI or URL of the endpoint to make a request from.
path Request path that is merged with the URI.
query Map of URL query parameters.
headers Map of HTTP headers.
requestContentType The value of the Content-Type request header. Defaults to 'application/json'.
contentType The value of the Accept request header. Defaults to the value of the requestContentType parameter if not specified.
body The request body to send. Can be a string, or if the requestContentType is "application/json", a Map or List (will be serialized to JSON).

Map data (optional) - A map of data to pass to the response handler.

Example:

include 'asynchttp_v1'

def initialize() {
    def params = [
        uri: 'https://someapi.com',
        path: '/some/path',
        body: [key1: 'value 1']
    ]
    asynchttp_v1.put(processResponse, params)
}

def processResponse(response, data) { ... }