Update device status with WEB API possible?

Questions & Help
,
1

After my first week of Homey App programming I’m able to interface with my device.
Got some flow cards to turn on- and color lights and make some sounds. Still in a premature state but we are getting somewhere.

I ‘have looked at sample coding and I’m still overwhelmed with the many possibilities and solutions, so I’m scratching only the top of the ice berg at this moment.

What, I want to improve is to get my Homey app updated if for example a user changes the light color from the device externally.
There must be a link to update the homey side also, to adapt to the new color.

And I have seen some possibilities about setIntervals to query the device status every x period but I want to use the Web API that also seems to be available.
So, my device will ‘push’ the change to Homey if a status is changed, Locally to my App that’s running on the Homey Pro 2023.

In the docs:

Your app’s API endpoints are available under the following url: /api/app/com.yourapp.id/. All endpoints are protected by default, and the requesting user needs permission to your app (which is granted by default after installation). You can override this by setting “public”: true.

But I tried all possible URL’s before /api/app/com.yourapp.id/ but none off them work.

What must it be? my app is called nl.woordklok.my:
https ://my.homey.app/api/app/nl.woordklok.my/getSomething?color=456789 does not work and gives an unknow page:

Unknown route
No match for /api/app/nl.woordklok.my/getSomething

If have created the endpoint in the app.json:

  "api": {
    "getSomething": {
      "method": "GET",
      "path": "/"
    }
  }

And created an api.js in the root:

module.exports = {
  async getSomething({ homey, query }) {
   // you can access the App instance through homey.app
    const result = await homey.app.getSomething();
    console.log("getSometing");
    return result;
  }
};

What I’m missing here? must the api.js included somehere or are there other things to solve?

2

my.homey.app is the hostname for the web app, not the hostname for API calls.

Assuming your Homey’s IP address is 1.2.3.4, you can use one of these:

  • http://1.2.3.4/api/app/nl.woordklok.my/
  • https://1-2-3-4.homey.homeylocal.com/api/app/nl.woordklok.my/

Or if you want to make the request to a publicly accessible URL:

  • https://CLOUDID.connect.athom.com/api/app/nl.woordklok.my/
    (you can find the value of CLOUDID here)

Notice that the path for getSomething is configured as being /, which means you don’t put getSomething/ at the end of the URL.

3

Thank Robert.

I tried this but it’s not working. I misunderstood how this should work initially.

I created the api.js and the endpoint in app.json but that seems not to be enough.

Wat are the basic steps to get this going?

Are there simple examples to learn from? I did not found any usable samples, all are seems to be incomplete to understand the hole flow that’s needed here.

4

Can you specify what “not working” means?

Creating api.js and placing the endpoint in app.json (make sure to place it in .homeycompose/app.json as the regular app.json file gets overwritten when the app is built) is all you need to do. And make sure to run your app on Homey itself using homey app run --remote

Here’s a minimal example: GitHub - robertklep/name.klep.apitest

5

Wauw :+1: Robert thank you for the example.

I installed it as is in my user folder and run it with:

homey app run --remote

 — App archive size: 16 KB, 10 files
✓ Installing Homey App on `Homey Pro van Aren` (https://192-168-2-114.homey.homeylocal.com)...
✓ Homey App `name.klep.apitest` successfully installed
✓ Running `name.klep.apitest`, press CTRL+C to quit

The I goto my browser and try to reach it:

https://192-168-2-114.homey.homeylocal.com/api/app/name.klep.apitest/getSomething

or
http://192.168.2.114/api/app/name.klep.apitest/getSomething

Both url’s give me: Cannot GET /api/app/name.klep.apitest/getSomething

That the same as what I have with me own app…
What can this be?

btw I have never seen this 192-168-2-114 is that also ‘normal’ in homey development?

6

I’ll quote myself again:

Notice that the path for getSomething is configured as being / , which means you don’t put getSomething/ at the end of the URL.

It’s what Homey uses “under the hood” to allow TLS/HTTPS access to local IP addresses.

7

ok so like this then:

http://192.168.2.114/api/app/name.klep.apitest/

result:

{
  "error": "Missing Session",
  "error_description": "Missing Session",
  "stack": "Error: Missing Session\n    at file:///app/lib/ManagerApi.mjs:61:43\n    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)",
  "statusCode": 401,
  "statusName": "HomeyErrorUnauthorized"
}
8

Yes, that’s expected, and documented:

All endpoints are protected by default, and the requesting user needs permission to your app (which is granted by default after installation). You can override this by setting "public": true .

9

Ok got it now, “public” : true added and it works.
And if I would generate an API key, and send it as the token I can put public to false.

Thanks so much for your help Robert :+1:

1 Like