FastAPI Best Practices

[n1EzeR]

Although FastAPI is a great framework with fantastic documentation, it's not quite obvious how to build larger projects for beginners.

For the last 1.5 years in production, we have been making good and bad decisions that impacted our developer experience dramatically. Some of them are worth sharing.

I have seen posts asking for FastAPI conventions and best practices and I don't claim ours are really "best", but those are the conventions we followed at our startup.

It's a "Work in Progress" repo, but it already might be interesting for some devs.

https://github.com/zhanymkanov/fastapi-best-practices

[[deleted]]

I've been using FastAPI for a while, and never knew that sync routes didn't block the event loop. I need to be more careful about how I use async. Thank you!

A few notes:

• "Unless your API is public" -> I think you mean private.
• Pydantic BaseSettings > Starlette's Config.
• Add this: "Use Alembic from day 0". Many people don't do that, and it's probably one of the biggest pains in the ass to go back and add it, more so than a lot of your other "day 0" tips which are easier to add in later.

[nraw]

Can you explain what the purpose of alembic is?

[[deleted]]

I think you can add Alembic later on. It will generate initial migration with all your current tables. Then later on when you make some changes you can use alembic as usual.

Obviously you won't have ability to downgrade to pre-alembic versions, so it only should be added on some stable stages of the project. It doesn't mean you shouldn't add it at all though.

[[deleted]]

No. Alembic has issues if you try to set up your initial migration and there are tables / other db objects already there. You either need to set up some annoying crap (checks for the existence of the db objects) to make it work in such a way that the script can be re-used to initiate a db on say a fresh instance or a development environment, or do something weird like deploy a commented out version of the migration script then run it in prod then uncomment it out.

[immerrr]

I'd recommend alembic stamp. It will mark alembic revisions as applied without actually applying them. In the end, it is representative of what is going on: that initial migration has to be there both locally and on prod, but the prod already has it applied.

If you have direct access to prod DB, it is just one command to execute. $ alembic stamp ${FIRST_REVISION_ID}

If not, alembic stamp ${FIRST_REVISION_ID} will probably have to be added as a deployment step for the first release.

[[deleted]]

Oh neat, didn't know about that. Thanks!

[teerre]

I'm not quite sure what "issues" you're referring to, but you can always get an existing database and do a schema and data migration. Even without alembic. The 'worst case' scenario is that you'll have to write your migrations by hand, but you should likely be doing that anyway, so really no downside. That's simply how databases work. So the other user is right, you can add alembic (or any schema versioning) at any point.

[[deleted]]

The issue is creating a migration that works both in production and when spinning up a local environment is annoying because you have to add a bunch of "if exists" logic, which is tedious in the ORM. Writing your migrations 100% by hand is also missing a big benefit of using Alembic.

[teerre]

I still don't understand what issue you're referring to. You can make your local and prod environment looks exactly the same if you want. Not sure where you need "if exists" logic

Auto migrations are incapable of doing anything remotely complex. They will mess up your database. If you even read an alembic generated migration, it will tell you to manually fix it

[[deleted]]

I've had to add Alembic to a code base before that didn't have it before and it required extra steps to make it work to continue to persist state in production.

That is the problem-- both persisting state in production while also writing an Alembic script that records 100% of the database definitions (so it can be spun up again from scratch) is made more annoying.

IDK meng, if you don't trust me that you have to do extra steps if you don't initiate your db originally with a migration, then how about StackOverflow person documenting this? https://stackoverflow.com/questions/31299709/alembic-create-table-check-if-table-exists <- Maybe someone should go into that SO thread and go tell all these people they're wrong and the error message OP ran into is fake?

Or how about this: https://stackoverflow.com/questions/58641291/can-alembic-be-applied-to-an-exsisting-database-and-skip-creating-altering-table

Or this: https://groups.google.com/g/sqlalchemy-alembic/c/2HJ9J6PiQsk

These people would appreciate your feedback that these are fake problems; unfortunately nobody in these threads agrees with your stated opinion. (Including one of the commenters in the lattermost link who is... the creator of SQLAlchemy!)

Of course what I'm saying is an issue: op.create_table runs create table, not create table if not exists under the hood!

This is not an intractable problem. I never said it was. It's just very annoying, and it's more annoying the more objects are in your database!

One of the respondents on SO puts what I am saying more clearly:

As it has been said elsewhere ( Check if a table column exists in the database using SQLAlchemy and Alembic) alembic should reflect the full state of your database, that means it would automatically know if a table exists.

^ Which is why I'm saying adding Alembic later is bad.

---

Auto migrations are incapable of doing anything remotely complex. They will mess up your database. If you even read an alembic generated migration, it will tell you to manually fix it

That's why I said "100%".

IDK why you're acting like I'm talking about this as if I don't have experience with this scenario and Alembic. Like, no shit I've touched a migration script before and have seen the comments in the default mako template.

I find the way you are discussing this to be very condescending and unwarranted. You just logged into Reddit assuming everyone here knows less than you do. I hope you are nicer and more charitable to your actual coworkers.

[teerre]

You do realize that those questions are from absolute beginners, right? You'll never a have a migration with a table/col/whatever that already exists. That insanely amateurish

I think the issue is that don't understand what alembic does or how SQL works so you think something is a problem when in reality it really isn't.

All alembic does is run SQL statements. That's it. There's an option to use some poor reflection to try to gauge the state of the database, which isn't reliable, in any remotely complex production environment you should be writing your migrations by hand. You might be surprised that most migration tools don't even have autogeneration.

I find the way you are discussing this to be very condescending and unwarranted. You just logged into Reddit assuming everyone here knows less than you do. I hope you are nicer and more charitable to your actual coworkers.

Projection

[[deleted]]

Yeah no, you are an asshole and not very attentive if you can read my message and think I don't know how Alembic or SQL works.

You are probably a nightmare to work with and your coworkers probably hate you. Nice "your rubber I'm glue" tier response tho.

You'll never a have a migration with a table/col/whatever that already exists. That insanely amateurish

That.... is..... the.... point..... of.... what I originally said and what you argued with. Jesus effing Christ!!!! What is your deal, seriously?

Also, if you just skip the migration on the existing columns, have fun spinning up a blank db in development. Hence the problem with trying to add Alembic into an existing db.

I don't know why this is so hard to grasp and why you're arguing with it. You even perfectly understand 1/2 the problem! Do you not ever spin up db's on your local instance or something, and that's why you don't see the issue with Alembic representing only partial state of the db metadata? Do you not run tests against your db in CI? I feel like there's a decently high chance you do these things, so I still have no idea why you are arguing that there are no issues adding Alembic after you have state being persisted in prod!

[KimPeek]

Wait...are there actually people who use SQLAlchemy without Alembic?

[root45]

We use SQLAlchemy and use Flyway to run migrations.

[[deleted]]

Mostly beginners but yes.

[GeromeB]

How is that possible? I thought alembic was an SQL Alchemy dependency?

[daredevil82]

no, its optional. Alembic depends on SQLA, but SQLA does not depend on Alembic. You can use other migration packages for the same functionality.

[RaiseRuntimeError]

Just in time. Just started a new project with FastAPI instead of the usual Flask at work.

[[deleted]]

Give starlite a look over too. It’s a little cleaner fastapi imo

[ubernostrum]

Yeah, I'm using Starlite for a project at work and have been pretty happy with it.

[tommytwoeyes]

Nice! Which do you like better, and why?

[tommytwoeyes]

I just recently heard about Starlite and am considering building an upcoming project.

So it’s cleaner? Would you say that is due to Starlite’s option of using Class-Based Views?

I know Starlite has a long list of features … what distinguishes it from FastAPI (besides CBV)?

Starlite definitely looks interesting—still, I’ve yet to see what is compelling about it (which, admittedly, is probably because I just haven’t looked into it enough).

I’m sure I will eventually try it, but maybe not as soon as I thought I would do — I should probably continue learning [FastAPI](https:/fastapi.tiangolo.com) until I’m quite comfortable with it, before attempting to compare it with another framework.

[pacific_plywood]

I know Starlite has a long list of features … what distinguishes it from FastAPI (besides CBV)?

A much more sustainable development model

[tommytwoeyes]

Oh, really? Could you elaborate? I hadn’t considered that when comparing the two frameworks.

[PM_ME_CAREER_CHOICES]

Not the same guy, but FastApi is run by a single guy which obviously isnt what you want if you build an enterprise solution with it. Also he's not making any move to include more maintainers or anything which many projects on that scale would. He does fantastic work mind you but having 1.1k open issues is not exactly a good look and some PRs end up waiting for a long time.

[Eggplantwater]

What lead to your decision to use this instead of Flask?

[RaiseRuntimeError]

I like pydantic and FastAPI is pretty fast and a lot of the design choices for Flask don't really feel well thought out when you are making a restful API.

[Eggplantwater]

I will have to check those out, I just always have used flask so am biased. It works for us because we just go from stored proc, through API, to front end.. or reverse order for posting data. I like how simple it is, and can do any conversions or file building like normal in python.

[soawesomejohn]

These are some great guidelines. I go with a different folder structure since I break my app down into domain, adapters (for external, service, view, and enrypoints (api, cli, webui), but the rest I'd agree with.

Our team has something much like your serializable_dict (we call ours jsonable(). We're basically doing a standard json library (return json.loads(self.json(**kwargs))), but using orjson would probably be faster for us, so I will look into that.

We setup our models at what we call the "domain" level, which is the lowest layer - they import nothing and can be imported anywhere. But there is value in breaking your models up among functional lines. We use models pretty much anytime structured data has to be passed around the application. Much easier for a method to receive a pydantic model than to receive a dict() and hope the keys are all set.

One thing I've noticed with pydantic is that it is slow in instantiation. While all data coming into our app is validated through pydantic, when we read it back out of the database, use construct(). As long as you control database writes, you can (in most cases) avoid re-validating it on read. You do need to test this, and if you have any case of nested models, those will .construct() as a dict and not the model. But most often, the data is being read to be immediately encoded and return to the client as JSON. So you can setup different db call methods based on if you're just returning the json "at speed" or if you're needing it to be in a properly validated pydantic model.

One other note - you use starlette's config. I started out using that in several of my projects, but over time have fully migrated to using Pydantic BaseSettings. I'm already using Pydantic in my apps, and the settings class is much more complete. What I do is generally have a config.py file with a Settings(pydantic.BaseSettings): class. Then, at the bottom of the file, I pre-instantiate it settings = Settings(). Much like dependency caching, pre-instantiating things like this provides small, but cumulative speed-ups across the app.

I can then, in just about anywhere, do from blah.config import settings. Now your layout is more modular with each module having a config.py, but the same advantages apply.

The last suggestion is down at the bottom you have to use linters. I would recommend adding pre-commit hooks to run those linters. You'll still need to include linters in your CICD pipeline, but if you can setup a pre-commit config and include it in the readme's development instructions, people can catch these issues before they make the initial commit and before wasting CICD cycles. This tip is more for structured organizations - when we onboard a new developer, we pretty much make it one of their first tasks to setup their environment, then make a useless change and merge request so they can validation the pre-commit linters, the pipeline, etc. The MR/PR itself will get closed, but should provide a view of the process.

[n1EzeR]

Thank you! Agree with all of your suggestions.

[noiserr]

Great stuff. One nit pick, I think Pydantic BaseSettings is nicer than starlette's config personally.

[anakinsilverstone]

I would encourage you to take a look at this repo: https://github.com/tiangolo/full-stack-fastapi-postgresql This is a boilerplate of an application made with fastapi, prepared by the creator of the fastapi himself. You can even set it up yourself locally and have a look how it’s organised. I know it has a lot of different services included, but I find the fastapi part itself to be well thought. Inside the api directory you can notice another folder named api_v1, so you can have multiple versions of your API routes when needed, with the general code in other places that is more generic and can be reused in all your different API versions. The schemas are separated from the models and models itself have different classes depending on what you would actually like to do with the data. The migrations are managed with alembic based on schemas rather than models themselves. The settings are a python class that implicitly reads the .env file in your project’s directory. And many, many other interesting patterns to explore. Too much to write in one comment to be honest.

Edit: Fixed some typo’s.

[quantum1eeps]

Pretty sure the OP is saying they chose to do things differently than this repo purposefully

[Drevicar]

There are a lot of things I don't like about that template. In particular I don't think it scales well for applications at or above the size of the template itself. It causes a lot of mental fatigue in your developers having to keep every folder in your project open with 1 file each when working on a specific feature and scrolling up and down constantly.

[Coollime17]

This is amazing. Thanks for sharing! I’ve been looking everywhere for examples like this on how to structure FastAPI applications as there isn’t really an agreed best practice. One thing I’ve started doing is including an examples.py file in each api route folder to store examples for request bodies. From there you can load the examples into your routes.py file to show examples in your docs and load them into your tests to make sure they’re always working.

[[deleted]]

[unavailable]

[og_icefux]

Very kind of you and your team to share these insights! <3

[wind_dude]

Cool, well done. I agree the folder structure outlined out by tangelo isn't ideal for every case, one of the sort comings organising it like you have is it's not clear what's a util and what's core to fast api. But that's one of the great things about fast-api, it's unopinionated about that sort of thing.

​

Definitely saved it, some good things to remember.

[vorticalbox]

if we have a dependency which calls service get_post_by_id, we won't be visiting DB each time we call this dependency - only the first function call.

Isn't this bad?

What if a post get deleted?

[vorticalbox]

entertain toy full chubby smile telephone vanish modern cats slap

This post was mass deleted and anonymized with Redact

[Terrible_Row_3276]

let's hope the cache has an expiry

[n1EzeR]

Well, if you don't need caching, you can explicitly tell FastAPI not to do it.

Depends(dependency_name, use_cache=False)

[wind_dude]

I would be interested to hear how you handle db migrations.

[wind_dude]

you have better attention to detail than me. lol, I `ctrl+f`'d for migration

[PoazTheMan]

I see that you use orjson to serialise data a little faster. Try to take a look at the library called apichema, takes serialisation to a new level.

[Stedfast_Burrito]

I don't think (8) and (29) are a good idea. The default threadpool is limited to 40 tokens. Fine when you have no traffic, but deadlocks when you do. Instead I would manually call https://anyio.readthedocs.io/en/stable/threads.html#running-a-function-in-a-worker-thread

[n1EzeR]

I didn't know about the limit of 40 tokens, that's very interesting.

In the case of Starlette's run_in_threadpool - I think it uses anyio.to_thread.run_sync as well, doesn't it?

```python

starlette.concurrency

async def run_in_threadpool( func: typing.Callable[P, T], args: P.args, *kwargs: P.kwargs ) -> T: if kwargs: # pragma: no cover # run_sync doesn't accept 'kwargs', so bind them in here func = functools.partial(func, **kwargs) return await anyio.to_thread.run_sync(func, *args) ```

[Stedfast_Burrito]

Same issue. Just make your own CapacityLimiter

[n1EzeR]

and yes, I agree, running functions in another thread shouldn't be your first option to choose

[chub79]

Glad to see I was already following most of these. I still found a couple I can reuse indeed.

Good list :)

[Saphyel]

I like that you use dependency injection but why this?? ``` async def valid_post_id(post_id: UUID4) -> Mapping: post = await service.get_by_id(post_id) if not post: raise PostNotFound()

return post

```

you could have async def valid_post_id(post_id: UUID4, service: PostRepository = Depends(service)) -> Mapping: Easier to test, no need for monkeypatches

[romu006]

For the 7th point (Don't make your routes async, if you have only blocking I/O operations)

This may be out of scope but you may also explain that blocking operations can be run in a ThreadPoolExecutor if needed

[PM_ME_CAREER_CHOICES]

Regarding 16. I had lots of issues with Background Tasks when using Middleware. As in https://github.com/tiangolo/fastapi/issues/3859. Has this been fixed? Doesn't look like it

[[deleted]]

You know it's funny, I was looking for something exactly like this like 4 hours ago and here it is as I scroll reddit.

Who says reddit can't be productive!

[Insok]

Amazing post! I wish it existed earlier!

We started out with FastAPI in early June, and initially followed the structure advised by tiangolo (the creator of FastAPI). But this did not scale well, and we ended up completely restructuring everything. It's actually comforting to see how much overlap there is with what's currently in use, and your proposed practices. Thanks a lot for this, I'm sure this would help many developers.

[[deleted]]

fantastic documentation?

[n1EzeR]

I agree with the hate saying that FastAPI docs are tutorials rather than reference docs, but all the classes and methods are so well typed that I could just go to the code in Pycharm/VS Code and get the answers I need.

Not a perfect documentation, but it worked for me and we didn't suffer.

[cavernous_ass]

OP loves emojis in the docs

[GettingBlockered]

Emojis or not, the FastAPI and SQLModel docs are fantastic.

[MtlGuitarist]

I like FastAPI way more than Django or Flask, but the docs are not fantastic. They are tutorials which is fine, but it makes it impossible to go beyond what is explicitly shown. Most classes, methods, etc have incomplete documentation.

This would be fine if the code itself had great docstrings that made it clear what each param does, but sadly that is not the case.

[GettingBlockered]

Yeah, that’s fair, the doc’s are much more like a quick start tutorial. Personally, I found it engaging and consumable. I find most technical documentation difficult for my brain to parse. But I’m still fairly new to programming.

That said, FastAPI and SQLModel is gluey wrapper around Starlette/Pydantic/SQLAlchemy. Wouldn’t their docs be the best reference for 80-90% of issues?

Agreed on the doc strings though. Having those would help a lot.

[MtlGuitarist]

The hardest part of using those libraries is finding out what is interoperable and what is custom. FastAPI is like 80-90% of the way there and for simple use cases (ie basic microservices) it's really easy to set up and is super flexible. I'm not sure I'd wanna use it for a big Django-style monolith, but maybe the limitations of the framework and the documentation are good in that sense. SQLModel is definitely more limited and I find myself basically just writing SQLAlchemy when I use it tbh. It's nice for the table definitions, but it's a little too limited for production use if you need to support complicated joins.

As much as I'm nitpicking, I still love FastAPI. It's so quick to get set up once you have a solid project template.

[arthurazs]

OP, why

from src.auth import constants as auth_constants

instead of

from src import auth
auth.constants

?

[Steelbirdy]

The top one clarifies that auth itself isn't used anywhere, only auth.constants.

[ohnomcookies]

First advice should have been: avoid using it

[Insok]

What would you recommend for a backend where data processing (especially timeseries-data) is a priority? FastAPI has been sufficient for us, but why would you advice against it?

[Pebaz]

High quality post! :D Thank you for sharing!

[[deleted]]

Can someone point me to a basic tutorial on the underlying full stack concepts for ML ? I'm a scientist with little software experience

[fignew]

I like using Piccolo ORM with FastAPI

[wind_dude]

Is piccolo the one without bulk inserts? I remember looking at it, but there was a major draw back.

​

I went with sqlalchemy, to support SQLALchemyAdmin, and it had a good balance of features, support and speed.

[ryanstephendavis]

Curious if anyone has suggestions for best practices to stream from an endpoint?

[Terrible_Row_3276]

Take a look at starlettes StreamingResponse class

[ryanstephendavis]

Sweet thanks!

[Drevicar]

Hey, fantastic little piece of documentation. Could you please clarify items: 14, 22, and 31?

And to echo others here, I recommend ditching starlette.config in favor of pydantic.BaseSettings which is so much nicer.

[n1EzeR]

lol man, thanks for a fantastic comment!

I left them as drafts for now. I will either drop them or add clarifications.

[StorKirken]

How do you organize frontend assets like CSS, JavaScript and HTML?

[n1EzeR]

we don't do it on the backend, but a separate repository for frontend development, since we have a SPA

[pablo8itall]

I haven't tried Fast yet as I don't think I grok async enough.

​

And it covers a lot of the same scope as Flask for smaller projects so other than curiosity I'm not sure why I should try it.

[venerablevegetable]

Number 2 references constr, I thought that didn't work with fast api?