Have you ever thought of making a programing interface without a clear definition first? If you start writing any program, then it usually starts or goes to a definition of an interaction interface. Whether it is header file for C or interface type for Java - it is a explicitly declared contract how to interact with part of your software.
Now, thinking of existing REST layer for openHAB - it is not based on interfaces other than RESTResource. It does not do a great job with explicit declaration of the interaction interface. Obviously there is always a way - cause you can go to demo.openhab.org and fetch specification from there.
Yet, this will not fly with multiple versions nor with new/old releases making it pretty difficult to utilize this spec. Additionally this resource is, from what I remember, based on introspection which forces you to declare all openapi annotations to influence output of generator. There were cases in the past where due to missing annotations output missed definition of types (i.e. marketplace addon definitions ~ 3.2 release).
It made me thinking - why we wouldn’t go with a different path by making a contract first approach. Starting with a subset which would serve a third contribution to rest api. This could simplify also other parts such as UI which will be then free of re-writing everything into basic http calls and could utilize generated javascript library generated from openapi (if there is such thing!).
Can you share your experiences in this area?
