How To: Call REST API from Hyperlink Tiles (Syntax)

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

Tiles that support Hyperlink action (tap to expand)
  • Monthly Calendar Tile
  • Weather Tile
  • Hero Attribute Tile
  • Clock Tile
  • Date Tile
  • Day of Week Tile
  • Media Tile
  • Variable Tiles
    • String Variable Tile
    • Number Variable Tile
    • True/False Variable Tile

: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

You can run a SharpTools Rule from any tiles that support the hyperlink action using the following syntax:

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

$.runRule() Parameters

The $.runRule() syntax also supports parameters which can be accessed as part of the HTTP Trigger context variables.

$.runRule("RULEID", {"button": 1})

Or customize the message that you plan on including as part of a notification:

$.runRule("RULEID", {"message": "Hello World"});

:warning: Dashboard Sharing: dashboards that are shared which use the special $.runRule() hyperlink syntax will not share the linked rule with your guest. Options include:

  • Use the native Rule Tile or Super Tile as those share the underlying rule resource
  • Create and share a separate dashboard with Rule Tiles on it just to grant your guest access to your desired rules. Those rules can then be used in hyperlinks in other dashboards that are shared with your guest.

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

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

@josh

Another question concerning using REST Endpoints and webCoRE. Hubitat webCoRE unlike SmartThings webCoRE allows for local REST Endpoints to be executed. Most browsers allow for POST commands to execute without needing a CORS poxy.

When using a Hyperlink tile with an example: ‘http://192.168.1.160/apps/api/306/execute/:e6...06:?access_token=21..466&key1=value1&key2=value2

The piston will execute local and avoid the cloud-2-cloud integration. Which is great, but it does then attempt to: “Open in Same Window, Open New Window, or Open in Modal”.

Is there anyway to just “Don’t do anything”?

You would use the special syntax mentioned above. The special $.get("https://your.url") syntax tries to make a REST API call.

I’m not sure this is accurate. It’s up to the server (the Hubitat hub in this case) and what CORS response it provides. In fact, it was a known issue with the Hubitat Maker API that you would get a Cross Origin Request error when making local requests directly from the browser… they later added an ‘Allowed Hosts (for CORS)’ setting to the Maker API to fix this for LAN connections.

CORS requirements are enforced when using JavaScript and in this case when you encase the local HTTP URL with $.get(“”) or $.post(“”) you do get stopped when it attempts the XMLHttpRequest.

CORS is not enforced when doing a simple URL POST and works fine when using a HyperLink tile, but then I am running into the “Open…” concern when it does execute.

When tapping the Hyperlink Tile without the special $.get() syntax or manually opening the URL in your browser, it’s just going to be a normal browser request (which is inherently an HTTP GET request).

The special $.get() and $.post() syntax enable you to make proper REST API calls without opening a webpage and they are JavaScript calls.

You could use the WebCoRE Hubitat Cloud endpoint or to ask the WebCoRE developers to see if they can figure out how enable a CORS header like the Hubitat team did with the Maker API.

I’m not sure what you mean here. Tapping the Hyperlink Tile or opening a new page is an HTTP GET request that inherently occurs when trying to navigate to a URL. Something like an old school <form> tag would cause a navigation/post-back event which would also be undesireable. JavaScript is the way to go here and either WebCoRE would need to be updated to support CORS headers or the Hubitat Cloud Endpoint would need to be used.

Thanks, but even using Maker API with a proper CORS request you then end up with a HTTPS site requesting data from a HTTP site and rejected. Hubitat would need a proper SSL certification to enable a local request with Maker API. Somedays things are uphill. :slight_smile:

Yeah, the Hubitat cloud endpoints are definitely the easier approach.

It’s somewhat of an undocumented feature, but you can technically add a custom SSL certificate to Hubitat. Some people have done that and have DNS entries pointing to the hub with a fancy domain name and everything:

2 Likes

Does this work from custom tiles?
I am getting a CORS error when calling an API from a custom tile. I’m using Axios and tried adding the config but didn’t seem to work.

    var config = {
      proxy: true,
      headers: {    
        "X-CMC_PRO_API_KEY": apiKey        
      }      
    }    
     axios.get(url, config)

Hey Ben. I think we covered this in the other thread now, but for documentation’s sake in this thread…

The proxy flag is unique to the first-party SharpTools tiles that support the REST API syntax noted in this thread. For a Custom Tile, you could use a third-party CORS proxy service – probably fine for generic API calls, but I would recommend against it for something where you need to include a private API key.

1 Like