POC: Frigate HTTP API FastAPI

[iursevla]

FastAPI POC

This is a POC of using FastAPI to replace Flask in Frigate HTTP API. It is using the defaults provided by FastAPI (uvicorn and starlette). This was discussed here. The intent is not to be merged right away but rather to further the discussion and to get your feedback on my proposals at the end of this description.

I'm proposing that we start moving to FastAPI by mounting Flask as a sub-application sub-application + 2. This means that the entire application still works as is and we can then start moving endpoint by endpoint to FastAPI until we get to a point where all endpoints are converted. At that point, we can remove Flask altogether.

I've started the conversion of 2-3 endpoints to showcase how it works:

• Preview endpoints:
  • /preview/{camera_name}/start/{start_ts}/end/{end_ts}
  • /preview/{camera_name}/start/{start_ts}/end/{end_ts}/frames
• Media endpoints:
  • /{camera_name}/latest.{extension} -> See warning below
• App endpoints:
  • /logs/{service}

Here it is working with FastAPI

converted_file.mp4

---

HTTP API Documentation

Without any extra effort, the swagger documentation is available at http://localhost:5001/docs or http://localhost:5001/redoc See documentation

See image && video

converted_file.mp4

The JSON/YAML schema can then be used to feed the HTTP API page without any human interaction.

From this documentation we can quickly create a client to be used by the front end. This can be done automatically with openapi-generator-cli. I've used this successfully multiple times at work and also for personal projects, e.g., Frigate HTTP API + 2.

---

Problems faced

Caution

I've faced a problem with the existing endpoints which have an extension suffix: .(jpg|jpeg|png|webp|gif).As a result ⚠️ This lines in nginx.conf was commented out. I've left a comment explaining the errors. If someone wants/can help me figure out why it is failing, then use my branch to debug the endpoints that contain an extension.

---

Proposal(s):

My main proposal is (assuming we can get the nginx problem I've faced resolved):

• Create a feature branch (or 0.15?) from the current development and merge this POC code in there.
  • We could start as simple as adding this: https://github.com/blakeblackshear/frigate/pull/13324/files#diff-15e7eac9ac660180d8d6be2ce993db57a3f8aa5d4b2a02333254024b6add7eb4R747-R753
• Then I can then start moving 2-3 endpoints a day/every 2 days to FastAPI and each time I create PR that can be reviewed and merged into the feature branch

Other proposals:

1. In the previous POC I was not specific about the types for each path/query parameter but we can be more precise with the types

Details

By being specific the endpoint will fail if invoked with invalid parameters

and we also get extra auto-complete on the docs

1. Add prefix to API endpoints e.g. media related endpoints should be /api/media/... this avoid any conflict between endpoints and makes it easier to read and more "RESTFUL".

   i.e., the following should all be `/api/media/...`

   

This can also be impactful if the user names the camera events which would end up requesting a different endpoint than expect (i.e., conflicts between ("/events/<id>/thumbnail.jpg" and "/<camera_name>/<label>/thumbnail.jpg"))

3. Split app.py file into multiple other route files:
   • Move the config endpoints to config.py
   • Move the timeline endpoints to timeline.py
   • Move the logs endpoints tologs.py
   • Move the app lifecycle endpoints (stats/version/restart/etc) to lifecycle.py

Proposals 2 and 3 probably should be left out for future implementation to avoid scope creep

[NickM-27]

I'd like to understand better what exactly was wrong with this endpoint

[iursevla]

Yes, me too. I tried to do some debugging and always ended up on the same line of code: https://github.com/encode/uvicorn/blob/47304d9ae76321f0f5f649ff4f73e09b17085933/uvicorn/protocols/http/httptools_impl.py#L165

If I invoked the API directly (i.e., localhost:5001 instead of localhost:5173/api...) it works just fine.

If any of you can take a look I'd appreciate.

To have more verbose logs and debug the code further I did the following:

Details

[NickM-27]

this is good to see, I was not sure how hard it would be to map these additional objects into the api class so they would be available to the handlers

[iursevla]

@NickM-27 @blakeblackshear how do you guys think I should go with this?

I'm continuing the conversion (You can see my progress here: poc-fastapi-continued), using the dev branch as the base (and I'll keep it up to date with upstream).

I'll convert all endpoints to FastAPI to see how it looks in the end.

[blakeblackshear]

I don't want to discourage you, but we are just focused on other things at the moment. I think the best path forward is to open a new PR. This one seems to have gotten a bit tangled up with other changes, so it was hard to review. In general, I like the approach you outlined where we lay the ground work and incrementally port over the endpoints.

I can probably track down those problematic endpoints once you open a new PR.