search

openhab / openhab-core

Core framework of openHAB
https://www.openhab.org/
Eclipse Public License 2.0
912 stars 420 forks source link

[REST API] Enhancement suggestion for Item "transformedState" field #1520

Open Rossko57 opened 4 years ago

Rossko57 commented 4 years ago

Background; when an Item [state presentation] (aka stateDescription/pattern) property includes a transformation, REST API GET items/itemName returns JSON with both raw Item state and transformed Item state. Example, item state=1 and MAPped to text -

{
  "link": "http://localhost:8080/rest/items/vnm_Intruder",
  "state": "1",
  "transformedState": "disarmed",
  "stateDescription": {
    "pattern": "MAP(alarms.map):intruder%s",
    ...

If there is no transformation specified in [state presentation] , the transformedState field is not returned at all.

However, the [state presentation] may call for formatting of state, or more recently for a QuantityType, call for units different from the actual Item. e.g an Item state 20.972 ˚C could be formatted using [%.0f ˚F] and value conversion implied. There is no easy way to get the expected 70˚F for external use.

It seems to me it may be useful to use the existing transformedState JSON field to also supply the "psuedo-transformed" state when no transformation is applied, but a style and/or units conversion is specified in Item [state presentation].

This needs thought about if it is a breaking change, but it is difficult to see that it would be. OH-3 may be a good break point to introduce a change.

ghys commented 4 years ago

That was actually implemented in the "displayState" introduced in https://github.com/openhab/openhab-core/pull/1364#discussion_r380606310 - so I'm all for it to be performed on the regular API calls as well.

Rossko57 commented 4 years ago

Okay, so the alternative change would be to add "displayState" field to regular REST Item JSON

mherwege commented 2 years ago

Anyone has any further thoughts on this? I ran into this myself when I used a webview in Basic UI to create an input field. I only have the state available from the REST API, not the displayState. My displayState does some number formatting on a QuanityType. Here is a sample of the REST API response:

{
  "link": "http://192.168.0.10:8080/rest/items/PVEtotalGS1",
  "state": "25248.837971875 kWh",
  "stateDescription": {
    "pattern": "%.0f %unit%",
    "readOnly": false,
    "options": []
  },
  "editable": true,
  "type": "Number:Energy",
  "name": "PVEtotalGS1",
  "label": "PV Productie Totaal GS1",
  "category": "energy",
  "tags": [
    "Measurement",
    "Energy"
  ],
  "groupNames": [
    "Solar_GS1",
    "PVEtotal"
  ]
}

There is no formattedState or displayState.

Another idea would be to create a specific REST endpoint: /items/{itemName}/displayState, retrieving the displayState (or state if it is equal to displayState). This would make it straightforward to use.