REST layer with contract first approach

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 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?

Yes, contract first is the way to go. A bit higher investment in the beginning, but it pays off nicely as you move forward.

There are code generates for many languages. However, not all code generates are neither great nor support all OpenAPI features - and some are buggy as in crashes on valid spec constructs. And some generates a code style that some developers dislike.

Despite all this, I would argue that it still better than code (annotations in the java world) generated specs (more difficult to keep APIs aligned in terms of naming and structuring).

One thing that is key; if you go for contract first - you definately need to use a codegen to generate your server (and client). I’ve seen contract first usage where the contract and server impl was 2 different things. And not in sync :scream:

Looks like someone did it with grapql: GitHub - magnayn/openhab-graphql: GraphQL Support for OpenHAB. :slight_smile:

1 Like