REST endpoints: Unify different approaches


(David Graeff) #1

Hello developer community,

this is one of a few Ideas I like the AC to consider for OH3.

The REST interface provides multiple endpoints. Unfortunately those feel like totally different subsystems with own data structures each. To ease the use I propose the following breaking changes:

  • Unify IDs: At the moment we have name for Items, UID for Things, id for extensions and uid for rules. Shorten this list to id and uid (those two are semantically different, so just id is not enough).
  • Unify Status reports: At the moment Things and Rules support an extended status report. But both endpoints do it differently.
  • Unify config handling: Some endpoints like the one for Things include configuration while other endpoints like the service+binding ones have a separate /config endpoint to retrieve configuration values.
  • Item handling requires a lot of knowledge in clients. Add REST endpoints to allow for requesting all possible Item types and item group functions. The client should not have a static list that runs out of sync at some point.

Cheers, David


(Rich Koshak) #2

I think this falls under the “make things simpler” category for sure. I’ll open a thread in the AC and link to this one. Let the discussion begin. :slight_smile:

My question as a non-developer, what are the impacts to the proposed changes? I imagine PaperUI/Habmin would be impacted but we are already talking about replacing those. Does it impact bindings, phone apps, sitemap UIs, rules?

These sound like reasonable changes to me.


(David Graeff) #3

All REST consumers including phone apps will be impacted. The required changes are minimal, but all apps have to decide if they want to support OH2.x or OH3 at that point (if they don’t do smart mapping).

Cheers


(YvesHanoulle) #4

for API changes like this, I think we can have an upgrade path similar to:

  • add the chosen “wording” to all rest endpoints
  • change the old way to update of the chosen one and mark it as deprecated.
  • give the interfaces the time to adjust to the new way of working
  • at some point change the old way to a readonly view. (as an extra push)
  • remove the old way

(David Graeff) #5

Usually yes. But considering that we have about 3 free-time/hobby core developers only atm, I’m not sure if its best if we just update all impacted solutions, including paper ui in one go without an upgrade path.


(YvesHanoulle) #6

Usually yes. But considering that we have about 3 free-time/hobby core developers only atm, I’m not sure if its best if we just update all impacted solutions, including paper ui in one go without an upgrade path.

Yes for the direct upgrade off all the interfaces when you can.
I would still advice to create an upgrade version for the API
If not, you will impact everyone who has created her own interface.

Adding the new one while still allowing the old one with a deprecated track , is not so much work in an API. It will prevent a lot of questions on the forums.
There are always cases people forget (or don’t know about) when they upgrade everything in one go.


(David Graeff) #7

I think it is possible with little amount of work to have for example “UID” and “uid” in json REST responses. I’m not so sure about the thing/rule status change, but might be simple as well.


(YvesHanoulle) #8

it might be a good test to see how this kindof unification works to start with the ID’s.
aka small changes, small impact


(Rich Koshak) #9

Or make this an OH 3 change and not have to deal with things that will be left behind like the current PaperUI.

This is a good point.I guess it depends on how beholden we are to these external interface builders. It would be friendlier for us to gracefully deprecate the REST API like what is proposed.

But the move from OH 2 to OH 3 is all about breaking changes. I trust the developers to decide whether the amount of work involved is beyond what is supportable.

Perhaps Yves’ proposal is a good way to give the rest of OH a chance to decide when/how to manage the upgrade without being forced to do so when OH 3 get’s released. If the move from OH 1 to OH 2 is any indication, the transition period will be quite lengthy. There are still OH 1 users who are just now looking to upgrade to OH 2. I would lot like to have to leave the OH 2 users behind re phone apps during that transition period.


(YvesHanoulle) #10

If the change is not to big, I think it would make sense to already do this in 2.x
This will also make moving to 3.x easier.

like @David_Graeff said for Id’s it’s probably very easy.

Other proposals that would really depend how different the endpoints are.
Yet even starting with using the same kind of name for all these endpoint would already make UI’s code a lot easier to write.


(Sebastian) #11

I think renaming the endpoints/parameters is good and can/should already be done in 2.x.

Could I additionally suggest that we get a more performant API (maybe sockets) at least for some parts (e.g. interaction with items/things)?
Connection on my local machine the Rest API tops out at about 30 updates / sec.


(Rich Koshak) #12

OK, so it looks like the nature of the AC and how it works is different from how I was thinking. Growing pains. :wink:

For a change like this you need to open an issue and make your case to the maintainers. If a consensus on the issue is impossible, you all can call on the AC to help break the impasse.

Given the wide ranging impacts I suspect only making changes in a way that doesn’t break everything all at once would be the only way to get the proposal past the maintainers.


(David Graeff) #13

I’m confused. This is the ESH replacement developer forum and such questions are best discussed in a forum and not in an issue. Even if the AC is not responsible, the maintainers which there are Kai and Maggu, should at least take a look at this topic, don’t they? ^^


(Rich Koshak) #14

I can’t answer the second part, but I think the implication is that to get their attention will be through a GitHub issue. I honestly never really understood what the ESH forum was used for except for the fact that it wasn’t really used that much. Maybe I was wrong.

From the AC perspective we are apparently here to help break impasses among the developers.

I don’t think the discussion here on the forum is a bad thing by any means, and as a user I like to see what developers are doing. But I also see that you are the only developer posting and most of the responses are coming from users. This is important feedback to have for sure, but we are not the only audience. I’ve been concerned about the lack of participation from the other maintainers. It would seem to get their attention an Issue is the medium.


(George Erhan) #15

I have followed your posts for a while and it seems to me that indeed you are committed to this project, but your diplomacy expertise is as low as mine! Please, pretty please don’t scare the valuable contributors on this forum!
Thank you, David.


(David Graeff) #16

The ESH forum was a forum software from 20 years ago and not very usable (and slow). That was my main reason not to use it. But you are right, other developers (at least core developers) are not participating here. So I will use GitHub issues then instead.

People can still follow up over there if they want to.

Actually since using this forum to discuss development ideas, I got highly de-motivated. No matter what you do and suggest, there is always one user that doesn’t like it.


(Rich Koshak) #17

That’s what happens when you have a lot of users. :slight_smile: We all have our own differing opinions.


(Łukasz Dywicki) #18

I am not a core developer, nor very active forum poster, but I am already concerned by amount of communication channels which are getting involved. Forum is very convinient for abstract ideas which didn’t have code background yet. Turning everything into github have serious drawbacks as this service despite of its abilities IS NOT a discussion forum. Github is all around code.
Making PR is one thing, bur what PR should contain? Same applies to issues which at moment of writing are unclear due to distillation which needs to take place.

I still remember authn & authz issue which been going over that for two years. With more than 80 posts it was far from managable conversation…

Anyhow, I will follow what is decided, but these are just my 0.02€.


(YvesHanoulle) #19

there is always one user that doesn’t like it.

That is the negative version

For me the positive version is: many users are using openhab and they want to keep using it with the features they like.
Remove ways of working and they complain. Add stuff and you won’t hear them.


(David Graeff) #20

A while ago I asked what the biggest core issues are for people. And my attempts in the community recently to.convice people of new ways is based on that.

Some issues cannot be fixed without changing something. What I’ve learned: don’t fix other people’s problems, because they will complain that something has to change.