Local API

pdlovelace · February 17, 2018, 2:08pm

Is there a local RESTful API accessible on the hub? I noticed that one of the recent release notes said “Local API”. If so, is there any documentation or pointers on how to use it? Preferably I’d like to get all list of all devices with all available detail if possible from the hub. I see from the web interface how to run commands and get websocket updates so I think that’s the only thing I’m missing… at this time.

chris.martin · March 9, 2018, 11:22pm

I’m interested in a local API as well. I was just about to switch from ST to Home Assistant (HASS) when I was told about Hubitat. Since HASS doesn’t have great support for Zigbee and most of my devices on ST are Zigbee based, I decided to grab Hubitat to replace my ST hub and go local and no more full dependence on cloud.
Now, I still really like HASS because it has a nice UI and a smartphone app. It also has integrations with my Ring Pro and Foscam cameras that won’t be available on Hubitat very soon. Also, the fact it has great integration with my router for presence detection.
So, I am currently thinking of migrating as much as possible from ST to Hubitat and for the rest go for HASS. This would give me full local processing and let me get rid of ST quicker.

A local API on Hubitat would allow me to use Hubitat as my Zigbee/Z-Wave gateway and use HASS as my main interface / UI to everything. So, it would be cool to be able to communicate with the Hubitat “world” via local API from my HASS install.

patrick · March 10, 2018, 12:27am

So, there isn’t an API but you can easily adapt ST based app / oauth2 endpoints like this:

github.com

open-dash/smartthings-api-smartapp/blob/master/smartapps/opendash/open-dash.src/open-dash.groovy

/**
*  Copyright 2017 Open-Dash.com
*
*  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
*  in compliance with the License. You may obtain a copy of the License at:
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
*  on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
*  for the specific language governing permissions and limitations under the License.
*
*  Open-Dash API SmartApp
*
*  Author: Open-Dash
*  based on https://github.com/jodyalbritton/apismartapp/blob/master/endpoint.groovy
*  weather code from https://github.com/Dianoga/my-smartthings/blob/master/devicetypes/dianoga/weather-station.src/weather-station.groovy
*  
*  To Donate to this project please visit https://open-dash.com/donate/
*/

This file has been truncated. show original

(not all these endpoints are replicated in Hubitat, but most should work once ported to Hubitat)

that essentially creates an api via oauth2 authentication. Then with what was referenced in the release note and noted elsewhere there are several calls to get the local path to that app and its endpoints.

chris.martin · March 10, 2018, 9:42am

I just noticed hub update 694 release notes mention “local API” under the enhancements. What does that mean in those release notes if there is no API on the Hubitat?

patrick · March 10, 2018, 3:01pm

The improvements in 694 are specifically to local api were to add the ability to get the local api endpoint for oauth2 enabled apps vs the cloud endpoint. I’ve updated that announcement to reflect this.

jason0x43 · March 30, 2018, 3:03am

General question: why would oauth be required to expose a local API? The hub itself doesn’t use any sort of security, so it seems odd that authorization would be needed for an API service.

patrick · March 30, 2018, 3:51am

couple reasons.

we have plans to add local authorization to the hub web interface that would be separate from oauth authentication.
oauth is required because the hub is available remotely through our cloud relay and we didn’t want two separate authentication flows for local vs remote endpoints. The app really has no context of if the request is local or remote (we hope to fix this at some point, but separate issue).

jason0x43 · March 30, 2018, 4:45am

Ah, that makes sense.

jason0x43 · April 2, 2018, 1:22pm

The calls used by the Hub’s web interface are essentially a local API, and they provide most of what I’d expect from one (endpoints to control devices, websocket connections for events). Is there any chance it could be made a bit more data-centric; like, provide endpoints to retrieve lists of devices and apps instead of rendering them directly to HTML tables?

patrick · April 2, 2018, 3:05pm

It’s on our wish list. The current routes can (and probably will) change and should not be considered an API.

jason0x43 · April 2, 2018, 3:19pm

Great!

Sure. I was just suggesting that the level of functionality they provide is very close to what I (and I'm sure others) would like out of a local REST API. (Well, and that some minor tweaks would make them more suitable for hacking until there is a complete API.)

patrick · April 2, 2018, 3:45pm

I have no idea what you are talking about, I’ve never used them that way… and I never would Especially not the endpoint that creates a backup and downloads it. No idea why that would be useful, who would want automated backups?

(warning, sarcasm in use, Monday after April Fools, call me jaded )

jason0x43 · April 2, 2018, 3:49pm

I’m using the backup one, along with the endpoints to read and write drivers and apps. Oddly enough, I hadn’t actually considered using the device control endpoints until this morning when a coworker asked me whether there was a local API.

christian · April 3, 2018, 5:12am

And I would be using the integrated API to send/pull data to my (remote) SPLUNK server so I can continue to have dashboards like these.

jason0x43 · April 14, 2018, 1:32pm

@patrick Do custom apps support any sort of push updates (e.g., websockets)? I noticed that the new Dashboard is polling every second or two rather than getting streaming updates.

patrick · April 14, 2018, 2:29pm

Yes and no. We decided to go the poll route for dashboard, but you’ll notice that most of the responses are empty. We only send changed events in the poll.

We hope to have a more socket like functionality in the future, but we wanted to get dashboard out and not hold back for a socket method.

Sockets work great on a local lan but trying to make it work for remote connections via oauth2 endpoints poses some unique challenges we have to work out.

Apps can subscribe to events for capabilities and then can send those changes to any URL ala web hook. This requires a server to receive these. Since a browser isn’t a server, dashboard couldn’t use this method either.

kewashi · August 10, 2018, 7:06pm

Hmmmm so I think I have been doing local access to Hubitat wrong in HousePanel based on this thread. I don't use OAUTH at all on the Hubitat auth side of my app. Sounds like I should. @patrick can you confirm?

If true as I suspect, then my next question is does this flow follow the same logic as SmartThings? That is, do I have to call once to get a "code" and then again twice (after the GET callback returning the code) to request the auth token and endpoint? I couldn't find this explained anywhere. I assume one just replaces graph.api.smartthings.com with cloud.hubitat.com ?

If this is in some other thread please point me to it.

chuck.schwer · August 10, 2018, 7:37pm

We actually have 2 oauth endpoints. There is the cloud one. which starts at https://oauth.cloud.hubitat.com/oauth/authorize

We also have a local endpoint you can use which starts at:
http://<HUB IP>/oauth/authorize

They follow the standard oauth2 flow, so you send client_id, response_type, redirect_uri and scope to the first url and go from there. (FYI response_type must be 'code' and scope must be 'app')

I have some example nodejs apps that use the local and cloud endpoints, but it uses the simple-oauth2 module so it might not be helpful if you are writing it in another language.

kewashi · August 10, 2018, 7:42pm

Thanks - this is super helpul. I'm writing in PHP so I think I can take it from here. If the flow uses a two stage auth as usual then I am all set. Actually, one point of confusion is what oauth endpoint to use for retrieving endpoints. SmartThings uses a different one for that than they use for access_tokens. I assume for Hubitat I just build the endpoint using the access_token and can skip that third step?

chuck.schwer · August 10, 2018, 7:51pm

Yes, we do use a 2 stage auth, it is just like the ST implementation.

In addtion, we do implement the endpoints url in both places: /apps/api/endpoints
you need to pass the Bearer token in the Authorization header with that call and it will give you the endpoints back.

One thing to keep in mind, we do not allow you to send the bearer token in the url as "access_token", you always have to use the Authorization header when sending the bearer token.