Discussion about API changes

[fredlcore]

Here you can discuss and suggest changes to the (JSON) API for use with external modules in other home automation systems.

[hacki11]

Speaking for iobroker, the user should not need to "migrate" iobroker-adapter settings himself depending on which bsb_lan firmware is used. It should just work out of the box no matter if new firmware, old firmware or the user did an upgrade with an existing adapter.
Introducing such "migration" steps scenarios depending on user based settings should be avoided at all.

Thats why i need to distinguish which api-version is currently available. This version should be incremented when breaking changes are introduced.
Api Versioning Strategies
I think for bsb_lan this will not fit because we are not supporting multiple versions. But perhaps a solution like Supported Versions would be feasable.

An endpoint or a field somewhere, where the current api-version is available. Of course the location of the field or endpoint should never change, because it will eliminate its own goal.

With this i can implement a new bsb_lan client supporting the new endpoints and maintain just one adapter version without getting incompatible with user who don't want to update bsb_lan firmware. Furthermore i still can bugfix older versions easily. I just have to check which api-verison is used (not existing for v1, and the endpoint for > v1) and select the right client.

[hacki11]

Good point, but if an endpoint is removed that version can not be read anymore. The version should not be part of the data, because it versions the data.

[hacki11]

It should be possible to request the version often and fast. If /JI contains too much data, there should be introduced an endpoint just for the version topic. (/JI is also data the version versions and should not be mixed, imho)

[dukess]

Clear. In this case adding new /JV command with payload {"version": "x.x" } looks better. Should we calculate API version separately or can use application version?

[hacki11]

Normally it is independent of application version. Totally fine to use separate version here

[dukess]

Done: #260
Payload: {"api_version": "x.y" }
Update: initial version is "2.0"

[hacki11]

Can you tell me the replacement of /JA? I'm fetching average values in json format here.

[fredlcore]

Parameters 20050-20099

[hacki11]

Does the JQ=20050,.. json response include the original ID?

[dukess]

Nope.
You can query /JI and get IDs from "averages" field.
or /JL from object with "id" == 13. Now /JL is more volatile but in future we can add text identifiers for parameters in additional to numbers for more readability.