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

[iursevla]

@blakeblackshear do you guys have a README on how to set up the whole environment to be able to contribute? I don't have much Python experience and I've tried for an hour with many errors popping up when I try to run the app.

I'm trying to see it running with Flask and then try to add FastAPI to one endpoint with Swagger

---

What I did:

1. Created venv https://stackoverflow.com/a/75696359
2. Run python3 -m pip install -r docker/main/requirements-wheels.txt
3. cd frigate && flask run

[hawkeye217]

https://docs.frigate.video/development/contributing

[iursevla]

Thanks @hawkeye217. I'm now developing the POC 🙏

A quickstart from my side, which might be useful for the contributing docs:

1. Clone project
2. Add .mp4 file to /debug named car-stopping.mp4
3. Start dev container
4. Inside dev container open 2 terminals and run:
   • python3 -m frigate
   • cd web && npm install && npm run dev

[hawkeye217]

Feel free to make a PR!

[iursevla]

Thanks @hawkeye217. Created a POC PR with 0.15 as target: #13324

Hope to get your and other maintainers feedback 🙏