[rest] Support sending Item command/state as JSON #4760

florian-h05 · 2025-04-27T21:59:44Z

Adds support for sending command/state through media type application/json to the existing plain text endpoints.

openhab-bot · 2025-04-27T22:03:04Z

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/integrating-openhab-and-garmin/155748/22

spacemanspiff2007 · 2025-04-28T03:43:06Z

What about state updates? If commands are available these should work, too.

Are you aware of the webhook binding?
Imho it tries to solve the same issue. Maybe it makes sense to consolidate into an official binding/endpoint?

TheNinth7 · 2025-04-28T05:15:34Z

Are you aware of the webhook binding?
Imho it tries to solve the same issue. Maybe it makes sense to consolidate into an official binding/endpoint?

@spacemanspiff2007,

I’m the original requester for this change.
I’m developing an openHAB app for Garmin wearables. The Garmin SDK doesn’t support sending web requests with raw content, as required by the current API for sending a command.

The Webhook binding also doesn’t natively support sending commands to items. You need to create a custom Webhook setup, which involves a relatively complex configuration using a JEXL script in the Thing and additional JavaScript processing.

To make the Garmin app accessible to a wider audience, it would be much better if the needed API support were provided out of the box.

spacemanspiff2007 · 2025-04-28T05:28:02Z

@TheNinth7
I'm not against using get requests to push data into openHAB, I explicitly support it.
This worked from OH1 - OH3 through Basic UI (unsupported) but then was unfortunately removed.

All I'm saying is that

state updates should be supported, too
maybe it makes sense to implement a subset of the webhook binding
maybe besides raw content json should also be supported for interacting with items, too

florian-h05 · 2025-04-28T08:16:31Z

What about state updates? If commands are available these should work, too.

I didn’t notice the method for this, I will add that.

maybe it makes sense to implement a subset of the webhook binding

I think there is some architectural difference here. The webhook binding won’t be allowed to directly control items as it is a binding, it provides a way to specify custom webhooks. I think its functionality being a binding only is fine, though it would be nice to be part of the distribution.
The changes I do are to allow usage of the REST API like webhooks, so you only need HTTP GET for accessing some REST API functionality that currently requires the use of different HTTP methods.

maybe besides raw content json should also be supported for interacting with items, too

That’s a good point, some clients only support posting JSON. It shouldn’t be a problem supporting multiple media types for the POST/PUT endpoints.

- Adds support for sending command/state as JSON to the existing plain text endpoints. - Adds new or extends existing endpoints where command/state can be passed through query params, allowing to send them from webhooks. Signed-off-by: Florian Hotze <[email protected]>

florian-h05 · 2025-04-28T12:20:11Z

So i am finished with adding the same functionality for states and JSON support for the existing send command/state endpoints.

openhab-bot · 2025-04-30T13:16:18Z

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-for-garmin/163891/1

splatch · 2025-05-02T13:16:47Z

Just a generic comment around the merit - for rest interfaces GET requests should issue read requests (as verb suggests), rather than write.
It is not a big issue for me, but it makes OH interface more of RPC. We already have some crippled implementation of toggle functionality for Android app, its just another edge case for another app.

kaikreuzer · 2025-05-04T09:48:26Z

Just a generic comment around the merit - for rest interfaces GET requests should issue read requests

This is the reason why I always argued against such a "feature" - it completely goes against the core principles of a REST API and GET requests being safe methods. I'm therefore still not a fan of adding that to our REST API. As @spacemanspiff2007 there was a "hidden" workaround in the past by having the Classic UI offering such an endpoint, which was not part of the REST API.

If the main use case is the support of webhooks, the approach with the webhook bindings looks much cleaner to me.

Just my two cents on the topic.

florian-h05 · 2025-05-04T15:43:04Z

What about splitting out the GET webhook functionality into a new core webhook API?
IMO it would be much more convenient to have support for sending commands and states directly without the need for a third party binding and linking channels.

TheNinth7 · 2025-05-04T16:51:06Z

From the perspective of the openHAB app I’m developing for Garmin, I can support both PUT and POST requests, with content types of either application/x-www-form-urlencoded or application/json. However, the Garmin SDK doesn’t always behave exactly as documented, so I’m happy to test in advance whichever approach you think best fits the openHAB REST API model before committing to an implementation.

spacemanspiff2007 · 2025-05-04T17:17:10Z

@kaikreuzer
I fully agree with you that it's completely against the core principles of REST.
But I'm also torn since it should be trivial to get data into openHAB.

Back in the days I had an old webcam on the only way to get notifications from it into openHAB was through a GET request because that was all the webcam offered. So it was either making that GET request work or nothing.
As you can guess I was not hesitant to use the workaround even though it was a dirty hack.

So I suggest that there is at least something or some way to provide more flexibility to ingest data, even though it's not the "proper" API.

Accepting json for commands / updates is imho a good idea in any case.
Maybe it makes sense to split this into two parts?

kaikreuzer · 2025-05-04T20:12:59Z

So I suggest that there is at least something or some way to provide more flexibility to ingest data, even though it's not the "proper" API.

Yes, I see the recurring request and see that there are many external services that don't follow REST principles, so I won't block any solution for this in core.

But I wouldn't advice to dilute the existing REST API and its endpoints by simply adding non-REST behavior to it like here.
It might be better to maybe introduce a new dedicated endpoint like /json-rpc/... next to the /rest/... ones to keep these things apart.

Signed-off-by: Florian Hotze <[email protected]>

florian-h05 · 2025-05-05T08:57:22Z

@kaikreuzer I have removed the new GET endpoints from this PR, it now only contains JSON support for the existing plain text command/state endpoints. Can you please review it?

digitaldan · 2025-05-05T14:34:49Z

I also like the idea of a JSON-RPC endpoint for this, its simple, follows a specification, and keeps the REST api clean. I also would definitely use this, i use Caddy to proxy and rewrite requests from a few devices who only support get requests for events. Would be nice to remove those rules.

kaikreuzer

Thanks!

jimtng · 2025-05-10T03:31:32Z

...ore.io.rest.core/src/main/java/org/openhab/core/io/rest/core/internal/item/ItemResource.java

+    @Consumes(MediaType.APPLICATION_JSON)
+    public Response postItemCommandJson(@PathParam("itemname") String itemname, ValueContainer valueContainer) {
+        return sendItemCommandInternal(itemname, valueContainer.value());
+    }


@lolodomo this made me think of you. I know we decided not to do it, but isn't this what you were trying to do but having trouble to do it? i.e. trying to accept either plain text and json.

Professing both MIME types is relatively simple, the most difficult part is getting Swagger work.

Signed-off-by: Florian Hotze <[email protected]> (cherry picked from commit 8ff69a3)

florian-h05 requested a review from a team as a code owner April 27, 2025 21:59

florian-h05 force-pushed the command-webhook branch from efbb7c4 to c913990 Compare April 27, 2025 22:06

florian-h05 marked this pull request as draft April 28, 2025 08:16

TheNinth7 mentioned this pull request Apr 28, 2025

Send commands via openHAB REST API TheNinth7/ohg#21

Closed

florian-h05 force-pushed the command-webhook branch from c913990 to a6c1f6b Compare April 28, 2025 12:16

florian-h05 changed the title ~~[rest] Add webhook-like endpoint for sending command to Item~~ [rest] Support sending Item command/state as JSON and through HTTP GET Apr 28, 2025

florian-h05 marked this pull request as ready for review May 2, 2025 22:15

Remove webhooks

b4630ce

Signed-off-by: Florian Hotze <[email protected]>

florian-h05 force-pushed the command-webhook branch from 06cfbb4 to b4630ce Compare May 5, 2025 08:54

florian-h05 changed the title ~~[rest] Support sending Item command/state as JSON and through HTTP GET~~ [rest] Support sending Item command/state through JSON media type May 5, 2025

florian-h05 changed the title ~~[rest] Support sending Item command/state through JSON media type~~ [rest] Support sending Item command/state as JSON May 5, 2025

kaikreuzer approved these changes May 9, 2025

View reviewed changes

kaikreuzer merged commit 8ff69a3 into openhab:main May 9, 2025
4 checks passed

kaikreuzer added this to the 5.0 milestone May 9, 2025

kaikreuzer added the enhancement An enhancement or new feature of the Core label May 9, 2025

florian-h05 deleted the command-webhook branch May 9, 2025 20:33

jimtng reviewed May 10, 2025

View reviewed changes

florian-h05 added a commit to florian-h05/openhab-core that referenced this pull request May 11, 2025

[rest] Support sending Item command/state as JSON (openhab#4760)

2d01518

Signed-off-by: Florian Hotze <[email protected]> (cherry picked from commit 8ff69a3)

Uh oh!

[rest] Support sending Item command/state as JSON #4760

[rest] Support sending Item command/state as JSON #4760

Uh oh!

Conversation

florian-h05 commented Apr 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openhab-bot commented Apr 27, 2025

Uh oh!

spacemanspiff2007 commented Apr 28, 2025

Uh oh!

TheNinth7 commented Apr 28, 2025

Uh oh!

spacemanspiff2007 commented Apr 28, 2025

Uh oh!

florian-h05 commented Apr 28, 2025

Uh oh!

florian-h05 commented Apr 28, 2025

Uh oh!

openhab-bot commented Apr 30, 2025

Uh oh!

splatch commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kaikreuzer commented May 4, 2025

Uh oh!

florian-h05 commented May 4, 2025

Uh oh!

TheNinth7 commented May 4, 2025

Uh oh!

spacemanspiff2007 commented May 4, 2025

Uh oh!

kaikreuzer commented May 4, 2025

Uh oh!

florian-h05 commented May 5, 2025

Uh oh!

digitaldan commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kaikreuzer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jimtng May 10, 2025

Choose a reason for hiding this comment

Uh oh!

florian-h05 May 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

florian-h05 commented Apr 27, 2025 •

edited

Loading

splatch commented May 2, 2025 •

edited

Loading

digitaldan commented May 5, 2025 •

edited

Loading