How To: Call REST API from Hyperlink Tiles

The latest SharpTools.io release includes support for making HTTP / REST API calls from any tile that supports hyperlink actions.

Tiles that support Hyperlink actions include:

  • Hyperlink Tile
  • Media Tile configured with a Hyperlink Action
  • News Feed Tile (with custom sources)

:warning: Important
The REST endpoint you are calling must be SSL encrypted. Most browsers will throw a mixed-content warning if you try to communicate with an insecure endpoint.

URL Format (Syntax)

To make an HTTP REST API call, configure your Hyperlink URL with a special syntax indicating the type of REST call you are making and optional payload (if supported).

HTTP GET :

$.get("https://your.cool.url")

HTTP POST :

$.post("https://your.cool.url", { "mantra": "This is the way"})

HTTP PUT :

$.put("https://your.cool.url", { "catchphrase": "I have spoken"})

HTTP DELETE :

$.delete("https://your.cool.url")

Run SharpTools Rule

$.runRule("RULEID")

:information_source: You can find the Rule ID in the URL while editing your desired rule.

https://sharptools.io/rule/edit/QT9hIErhEQxISxa20mYR
                                ↑ Rule ID

Proxy Support (IFTTT, WebCoRE)

We’ve added an optional configuration object which enables you to configure the HTTP REST API requests to proxy through SharpTools servers. This is often helpful for services like IFTTT or WebCoRE which have issues receiving requests directly from browsers. (eg. CORS configuration issues).

To use this feature, pass a configuration object as the last parameter with a ‘proxy’ key set to true:

HTTP GET

$.get("https://maker.ifttt.com/trigger/change_volume/with/key/XXXXX", {"proxy": true})

HTTP POST

$.post("https://your.cool.url", {"volume": 10}, {"proxy": true})

Headers Support

The Hyperlink REST API syntax now supports an optional configuration object which supports passing in a set of headers to include in your REST API call.

$.get(url, config)
$.post(url, data, config)
$.put(url, data, config)
$.delete(url, config)

This means you could include custom headers needed by your API:

$.post("https://mycoolapi.com/update", {}, {"headers": { "X-Species": "Ferengi"}})

Note that you’ll need to pass an empty data object {} for the post and put calls if you don’t have any payload.


Note that these requests are made directly from your browser, so you can make requests to LAN devices, but since SharpTools is served over SSL, your local endpoints must also have a valid SSL certificate. One approach to this is to use a small webserver on a NAS or Raspberry PI to create an SSL proxy.

2 Likes

This works great with Hyperlink tiles with Hubitat WebCoRE!

$.get("https://cloud.hubitat.com/api/bd7e....69ef/apps/306/execute/:e6a...47e06:?access_token=21a1....7466&yourKey=yourValue&yourKey2=yourValue2", {"proxy": true})

2 Likes

@josh is there a way to set a $variable with the URL path and then use that $variable in the Hyperlink REST API?

For example set a </> Variable:

$piston =  https://cloud.hubitat.com/api/bd7e....69ef/apps/306/execute/:e6a...47e06:?access_token=21a1....7466

then use it like such:

$.get($piston+"&yourKey=yourValue&yourKey2=yourValue2", {"proxy": true})

I am reusing the same piston several times passing different key:value pairs. If there comes a day I need to redo the piston - it will require that I change the path everywhere, so hope there is path todo something like this.

Not at the moment, but it’s a neat idea.

@James has been working on some proof of concepts around using variables in Rule Engine Notifications which requires a similar ability to inject a variable into a string though…

And we have an Rule Engine: HTTP Webhook Trigger feature request topic created, so I’ve gone ahead and created the other side of that which would be a Rule Engine: HTTP Request which you may want to vote on.

My thought is that you could create a rule (or rules) to make the HTTP requests and if those had the ability to mix variables in with other text, it could achieve what you’re looking for.