API Scapegoat Add-on - A simple API gateway with failover capabilities for your REST sensors!

Share your Projects!
,
1

A Problem

Lately I’ve been getting into Home-Assistant and spent a few days configuring stuff and trying things out.

Then I started using REST sensors and REST commands so I’m able to change the picture mode of my Sony Bravia TV, this is when things got tricky, because as soon as my TV’s power is cut off, my Home Assistants log got spammed heavily by the REST sensors not being able to reach my TVs API anymore, I didn’t like that.

Down to the present day, there is no way to disable sensors or set their scan interval to manual, there is a workaround where you can set the scan_interval to 30 years and then use automations to update the sensors, BUT this trick does not work for REST sensors as they have their own retry mechanism which forces the sensor to try every 180 seconds to reach the API, so my log is still spammed heavily.

The Solution

Since my Python knowledge is basic at best and I couldn’t find a quick fix for setting the scan interval of sensors to manual, I came up with something else.

So why bother if a device is offline when something else could simply take its place instead?

Presenting API Scapegoat

A simple to use API gateway to substitute your offline APIs when they are not available.

With a simple configuration like this, you can prevent your rest sensors from going offline ever again

route: /api
target: 'http://yourdevice.local:8080'
failover:
  response:
    headers:
      content-type: application/json
      server: API Scapegoat
    body: '{ "status": "api offline" }'

All you need now is to use the ip or hostname of api-scapegoat now. To get the hostname or ip simply open the WebUI of API Scapegoat, it will be shown there. You can always expose the add-on port as well to make it available for your whole network.

  - platform: rest
    name: My device status
    resource: 'http://61b09487-api-scapegoat:3000/api/systeminfo'
    method: GET
    value_template: {{- value_json.status -}}

That’s it, your REST sensor will now report “api offline” if your device is not available for whatever reason! As soon as your device is back online again, API Scapegoat will simply forward the requests again to the device. This way HA will recognize your sensor way faster than before since the REST platform can stay initialized forever!

The same can be done with REST commands, technically even with media players or other components which use HTTP or websocket APIs to communicate, though your mileage may vary.
For more features and explanations just look at the README.

Save power!

Now you can safely cut the power from your devices without having to restart HA or having your logs spammed.

TODOs left

There are a few things I haven’t done yet but I’m planning to, for example

  • create a prettier Web UI with info about currently proxied APIs
  • allow API Scapegoat to listen on multiple ports
  • allow request & response manipulation to get the full power over your APIs
  • create a regular Docker image for the standalone version so people can easily use it with standalone Home Assistant as well

I’m open for suggestions as well. :slight_smile:

Thanks

A big thanks goes to @frenck for all his templates and the pipeline jobs which made life easier and got me way faster into add-on development for Hass.io than it would have without them. Especially because the add-on now has multi-arch support for all platforms!

3 Likes