Showcase strong typed Typescript client and OpenAPI specification proposal

[iursevla]

For my ongoing project (intruder-detection) I rely heavily on Frigate NVR and I needed to use its HTTP API.
Doing so I faced some problems:

• There was no client for the API (at least didn't find any from my searches) and the client needed to be NodeJS/Typescript one since that's what I'm using for my project.
• There was no OpenAPI specification for the Frigate HTTP API, which would enable me to create a client for the API quite easily (dare I say trivially using openapi-generator)
• The existing documentation for the main branch or the beta branch has a lot of missing details (missing URL parameters/query parameters/body types, missing endpoints, endpoints that no longer exist/etc)

To create the Typescript client I had to dive deep into the code and read each endpoint. I've tried my best to make sure each endpoint has the required information to build the Open API specification:

• URL parameters
• Query parameters
• Body
• Response - I've also added examples for the majority of the existing endpoints

The Open API specification for the Frigate HTTP API is available at https://intruder-detection.github.io/frigate-http-api-typescript
This should make it easier for anyone to read through the documentation of the Frigate HTTP API.

The Typescript client that I've created is available at https://github.com/intruder-detection/frigate-http-api-typescript

---

My proposal, is that we start using some tool that builds the HTTP API specification automatically (e.g., https://pypi.org/project/flask-swagger/).
The benefits would be:

• There's no need to maintain an extra file with the HTTP API types - which we've seen easily get out of date
• Users can easily create a client for the HTTP API in their language of choice

[iursevla]

@blakeblackshear @NickM-27 Let me know your thoughts on this one. You guys have plenty of experience with Python and the current Flask version being used in the Frigate HTTP API, so let me know if this is easy to do.

If this is not easy/is cumbersome to do, then as an alternative, we could move my yml definition into the Frigate project and then show the Open API specification in this page. This way, we would only need to maintain the Open API specification, which IMO is much easier to maintain than markdown.

[blakeblackshear]

I think this looks great, and we should also consider generating the Typescript client to use in the frontend as well so we get better type checking for our frontend code.

Do you know of an existing project that we could use as a reference for patterns here?

Are you interested in submitting a pull request for this?

High level, what I have in mind is:

• I'm assuming we need to annotate API methods in the source code with some documentation
• The swagger UI is automatically built and included in frigate
• We would be able to run a command to generate an updated typescript client for use in the frontend
• The typescript build of the frontend would do all the type checking against the newly generated client at build time

[blakeblackshear]

flask-swagger appears to be unmaintained. I think it probably makes sense for us to consider moving to something like FastAPI instead of Flask with builtin openapi spec support.

[iursevla]

I think this looks great, and we should also consider generating the Typescript client to use in the frontend as well so we get better type checking for our frontend code.

Thanks, my pleasure to contribute a little to this project.

Are you interested in submitting a pull request for this?

Yes, I am. Assuming we are in a stable place in terms of the API side. But

flask-swagger appears to be unmaintained. I think it probably makes sense for us to consider moving to something like FastAPI instead of Flask with builtin openapi spec support.

I was wondering about that. I don't have much experience with Python but Flask seems to be outdated in some sense. In this scenario before we dive into this do we want to create a separate discussion for this? Maybe other contributors have XP with FastAPI and/or other frameworks and can chime in with the pros&cons.

We would be able to run a command to generate an updated typescript client for use in the frontend

Yes, I assume we can use https://openapi-generator.tech/docs/generators/

---

In the next few days, I'll do an experimental version using my mostly "hand" generated version at https://intruder-detection.github.io/frigate-http-api-typescript/. I'll try to see if I can use the Frigate API of my deployment with this generated Typescript code.

[blakeblackshear]

Migrating to FastAPI will be a major change, so we wouldnt consider it until 0.15.x at the earliest. Not sure how much we want to invest in building this around Flask.

[iursevla]

Not sure how much we want to invest in building this around Flask.

I don't think we should invest much (if any) time now if we're thinking on moving to FastAPI.

Migrating to FastAPI will be a major change, so we wouldnt consider it until 0.15.x at the earliest.

I can start looking around to see how hard it is. I'll try a simple controller (export.py) and see how it goes. Then I'll post my findings here on in a new discussion.