Migrate API usage from TypeScript code to typesafe @hey-api

[jsjames]

For post 5.1 release

• Initial draft of api using fetch and @hey-api to autogenerate api code.
• modified a few instances of api calls (WIP), pending review of overall structure

[relativeci]

#4402 Bundle Size — 12.75MiB (+0.15%).

7152b76(current) vs 520c0bb main#4398(baseline)

Warning

Bundle contains 2 duplicate packages – View duplicate packages

Bundle metrics   2 changes 1 regression

	Current #4402	Baseline #4398
Initial JS	1.57MiB(+1.17%)	1.56MiB
Initial CSS	0B	0B
Cache Invalidation	6.93%	6.93%
Chunks	615	615
Assets	696	696
Modules	2450(+0.53%)	2437
Duplicate Modules	0	0
Duplicate Code	0%	0%
Packages	128	128
Duplicate Packages	1	1

Bundle size by type   1 change 1 regression

	Current #4402	Baseline #4398
JS	11.05MiB (+0.17%)	11.03MiB
CSS	876.93KiB	876.93KiB
Fonts	526.1KiB	526.1KiB
Media	295.6KiB	295.6KiB
IMG	45.73KiB	45.73KiB
Other	847B	847B

Bundle analysis report Branch jsjames:api Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[jsjames]

@florian-h05 - a few things to get your input:

• in the existing api, all the framework7 request promises were wrapped to reject the promise on a caught error. Is there any reason we wouldn't just throw the error?
• I haven't done much error checking yet in this implementation - so once we are okay with the structure, I can continue to make progress.
• I'd like to pull the openAPI spec from the source vs. demo.openhab.org - I have an enquiry on the forum for this - but if you might be able to point me in the right direction here.

any other feedback on overall structure? If not, I can continue to port calls over to this.

[florian-h05]

First of all, great PR.
I've already used hey-api in a university project and having a fully typed API client without needing to write type defs on our own is great!

in the existing api, all the framework7 request promises were wrapped to reject the promise on a caught error. Is there any reason we wouldn't just throw the error?

I think this was done to "simplify" error handling so you can simply check err === 'Not found' in the .catch block of a promise. But I always found this quite confusing, to let's throw the full error and then check err.statusCode === 404 instead.

I'd like to pull the openAPI spec from the source vs. demo.openhab.org - I have an enquiry on the forum for this - but if you might be able to point me in the right direction here.

I have to look into how to get the OpenAPI spec from the source.

[florian-h05]

WRT to the general structure, I will have a look at this PR after the 5.1 release.

[jsjames]

WRT to the general structure, I will have a look at this PR after the 5.1 release.

FYI - @wborn helped me understand how the openapi spec is generated. I think this will be a bit iterative as there may be some enhancements to the openapi spec which will help to make the interface generation better (for instance removing the DTO from some of the object names and further specifying which fields cannot be blank.

For now, I've been modifying a local version of openhab-core and generating the spec and use that to build the interface. Eventually though, if we get all the changes done and submitted to core, we can pull the spec from there.

[jsjames]

@florian-h05 - a few updates:

• I've submitted a PR to core to enhance/correct some ares of the openapi spec - which is generated at runtime using the swagger annotations. I have build a version of core and extracted the openapi spec that is currently in the build directory. So, assuming the PR will get approved, the spec will match what we feed into hey-api.
• I do expect we will find additional issues as we expand typescript in the ui that we might need to address in the core openapi spec.
• Lastly, the one thing that is not in the current openapi spec is whether a field is required or optional and as such, all generated typescript interfaces have all the fields as mandatory. As we find fields that are optional, we can annotate them in core so they will be automatically generated. I don't know of a more automated process to do this - so I think this will be manual.

[jsjames]

@florian-h05 - this one is ready for your review. I have a parallel PR into core to enhance the open-api spec schema - however it does not need to be submitted before this one as I've built a version locally to generated the openapi spec currently in the build directory.

One enhancement is that the spec will now specifiy required vs. optional fields - unfortunately, there doesn't seem to be a systematic way to do this. It might be worth you looking at the generated api/types.gen.ts file to see if there are other enhancements. I can make those then in core if you see areas to update as we should keep the master spec the "source of truth".

All-in-all, I think its a good way to setup the api - and have modified several components/files with the new setup. The old one still exists and we can remove over time.

[Copilot]

Pull request overview

This PR implements a new API layer using @hey-api/openapi-ts to auto-generate type-safe API methods from OpenAPI specifications. The changes replace manual type definitions and API calls with auto-generated ones, improving type safety and maintainability.

Key changes:

• Auto-generated API types and methods from OpenAPI specification
• Replaced manual type definitions in src/types/openhab/ with generated types in src/api/types.gen.ts
• Updated multiple components and stores to use the new generated API methods
• Added API interceptors for authentication and error handling in src/js/initApi.ts

Reviewed changes

Copilot reviewed 46 out of 58 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/types/openhab/*.d.ts	Removed manual type definitions (replaced by generated types)
src/api/types.gen.ts	Auto-generated TypeScript type definitions from OpenAPI spec
src/api/index.ts	Exports all generated API methods and types
src/js/initApi.ts	Configures API client with request/response interceptors
src/pages/settings/transformations/transformations-list.vue	Updated to use generated getTransformations() and deleteTransformation()
src/pages/settings/menu/settings-menu.vue	Updated multiple API calls with error handling
src/pages/analyzer/*.ts	Updated type imports and API usage
src/js/stores/*.ts	Updated stores to use generated API methods with improved error handling
src/components/config/controls/*.vue	Updated components to use new API methods
bundles/org.openhab.ui/web/eslint.config.js	Excluded generated API files from linting

Files not reviewed (1)

• bundles/org.openhab.ui/web/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Unused variable dest.

Suggested change

const dest = './openapi.json'

[jsjames]

No, not yet. I should probably do.

I just looked at the core code and it looks like the schema is correct and aligns with the core code. I think we should be good here.

I was expanding this to the thing-details page and it looks like there is an issue with how the PUT is described or I'm calling it wrong. Let me figure this out first before merging.

[jsjames]

No, not yet. I should probably do.

I just looked at the core code and it looks like the schema is correct and aligns with the core code. I think we should be good here.

I was expanding this to the thing-details page and it looks like there is an issue with how the PUT is described or I'm calling it wrong. Let me figure this out first before merging.

I'm at a loss on this one - I have the code here: thing-detail-api. SImply enabling/disabling a thing will not work. I believe hey-api is generating incorrect code for this and have filed an issue. If you get a sec, maybe you can spot an issue?

[jsjames]

I'm at a loss on this one - I have the code here: thing-detail-api. SImply enabling/disabling a thing will not work. I believe hey-api is generating incorrect code for this and have filed an issue. If you get a sec, maybe you can spot an issue?

So, in digging around in the hey-api code more, I think this is definitely a bug in generated api client. See my explanation here: hey-api/openapi-ts#3250

Not sure if you have suggestions on how to fix?

[jsjames]

I'm at a loss on this one - I have the code here: thing-detail-api. SImply enabling/disabling a thing will not work. I believe hey-api is generating incorrect code for this and have filed an issue. If you get a sec, maybe you can spot an issue?

This is definitely an error in the hey-api code - I have submitted a PR to openapi-ts: #3255 and included an interim patch for this PR. Things are now working for put/post.

[jsjames]

This is definitely an error in the hey-api code - I have submitted a PR to openapi-ts: #3255 and included an interim patch for this PR. Things are now working for put/post.

hey-api has already merged in this PR (they did make the fix in a different way). I have updated this PR with this new hey-api version and its working well. So, we can move forward with this merge.

[florian-h05]

Glad they are still that fast in fixing bugs and releasing a new version ... I've also discovered a bug and proposed a fix in hey-api about a year ago when using it in a university project.

[florian-h05]

@jsjames I have created #3812 which refactors some code to TypeScript and makes use of @hey-api there.
I would propose to migrate to TS Composition API step-by-step, whenever we like to rewrite something.

[mrlubos]

Glad they are still that fast in fixing bugs and releasing a new version ... I've also discovered a bug and proposed a fix in hey-api about a year ago when using it in a university project.

@florian-h05 I'm everywhere 🕵️‍♀️ let me know if you have any more feedback in the future!

[florian-h05]

@mrlubos You indeed seem to be everywhere, for now I don't have further feedback. Many thanks for your great work at hey-api, my experience so far has been really good, no major issues!

[jsjames]

@jsjames I have created #3812 which refactors some code to TypeScript and makes use of @hey-api there. I would propose to migrate to TS Composition API step-by-step, whenever we like to rewrite something.

Okay - so we don't want to migrate existing non-TypeScript code to use the hey-api functions? We'll just migrate when we migrate that code to typescript? I did convert several over already to the new api.

Should we add anything to CONTRIBUTING.md regarding using the new hey-api protocol?

[florian-h05]

I was thinking about this as well, theoretically we can migrate anything, but if something changes with the OpenAPI Spec and the API client changes, does Vue-tsc catch invalid usage of the API client in pure JS code?

[jsjames]

I was thinking about this as well, theoretically we can migrate anything, but if something changes with the OpenAPI Spec and the API client changes, does Vue-tsc catch invalid usage of the API client in pure JS code?

I don't think you get any typescript benefits in incorporating in plain js code. I see the benefits:

• more robust call format to the api - consistent parameters
• If we want to improve error handling in api calls - i think we should migrate to the new calls to be consistent and eliminate the need to recode error handling in the future
• new api handles 204 (so at a minimum we should migrate those)
• we are bound to find new issues with the openapi spec as we expand to other areas - i'd rather find those out sooner rather than later

Having said that, we risk breaking things by converting - so its a risk.

[florian-h05]

Yeah, overall I agree everything should be migrated, I am just not sure about the exact schedule. But if you want to go ahead and convert all usages, fine for me 👍