Work That Runs After the Response
FastAPI's BackgroundTasks runs a function after the answer has gone, so a caller never waits for a confirmation message or a log entry, 202 Accepted says slow work has been taken on, and a job queue such as Celery or RQ is what keeps work safe when it must survive a restart.
Freelancer · FastAPI · REST API · Updated
After this lesson you can
- Run work after the response with BackgroundTasks and add_task, passing the function and its arguments without calling it
- Choose between BackgroundTasks and a job queue such as Celery or RQ, and answer 202 Accepted for work that finishes later
Key takeaways
- Work the caller doesn't need to see, such as a confirmation message or a log entry, shouldn't make the caller wait for it.
- A route takes a BackgroundTasks parameter, and add_task(function, arguments) runs that function after the answer has been sent. Pass the function itself, not a call to it.
- 202 Accepted means the request was taken on and its work will finish later. The answer says where to look for the result.
- Background tasks live in the server's memory. If the server stops before they run, they're lost, and if one fails, the caller already has its answer.
- BackgroundTasks is the small version of a job queue. Celery and RQ keep jobs in a store of their own, run them in separate workers and try them again when they fail.
You sign up for an app, the page says "Welcome!" at once, and the confirmation email turns up a few seconds later. The app didn't make you wait for the email: it answered first and sent the email after. Every API has work like this, the kind the caller doesn't need to see happen, and this lesson shows FastAPI's way to do it after the answer has gone.
The example is Movie Night Picker again. When the group picks a film with POST /picks, the API saves the pick and posts it to the group's chat.
An answer that waits for the chat
Posting to the group chat takes a couple of seconds: here time.sleep(2) stands in for the chat service, and print for the message it would show.
import time
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI(title="Movie Night Picker")
PICKS = []
class PickIn(BaseModel):
film_id: int
picked_by: str
def post_to_group_chat(pick):
time.sleep(2) # the group chat service takes a couple of seconds
print(f"Group chat: {pick['picked_by']} picked film {pick['film_id']} for tonight.")
@app.post("/picks", status_code=201)
def add_pick(new_pick: PickIn):
pick = {"id": len(PICKS) + 1, **new_pick.model_dump()}
PICKS.append(pick)
post_to_group_chat(pick)
return pick
POST /picks with {"film_id": 3, "picked_by": "Rosa"} answers 201 Created with the new pick:
{"id":1,"film_id":3,"picked_by":"Rosa"}
It takes over 2 seconds, and the terminal running the server shows the chat message:
Group chat: Rosa picked film 3 for tonight.
Rosa waited two seconds for a message she didn't need to see. The pick was saved after a few milliseconds; the rest was the chat.
BackgroundTasks: answer first, then the rest
Think of a cashier who hands you your receipt, then restocks the shelf after you've left. You don't wait for the shelf. FastAPI's BackgroundTasks works the same way: give a route a parameter with the type BackgroundTasks, and FastAPI hands it a list of jobs to run once the answer has been sent.
from fastapi import BackgroundTasks, FastAPI
@app.post("/picks", status_code=201)
def add_pick(new_pick: PickIn, background_tasks: BackgroundTasks):
pick = {"id": len(PICKS) + 1, **new_pick.model_dump()}
PICKS.append(pick)
background_tasks.add_task(post_to_group_chat, pick)
return pick
add_task takes the function and then its arguments, separately: add_task(post_to_group_chat, pick), read "add task: post to group chat, with pick". Now the same request answers the same 201 in a fraction of a second, and the chat message appears in the terminal two seconds later.
The mistake to watch for is add_task(post_to_group_chat(pick)). The parentheses call the function right away, so the caller waits two seconds again, and add_task gets the function's result, None, instead of a function. Once the answer has gone, the server's terminal shows the error: TypeError: the first argument must be callable.
A task can be a plain def function, which FastAPI runs in its thread pool, or an async def one, which it awaits on the event loop, the same rule as routes in Async Routes: When They Help, and When They Don't. What runs when: the route's own code, then the answer goes out, then the tasks, one after another in the order they were added. A route's get_db, written with scope="function" as in A Database Connection for Every Request, has committed and closed its connection before the answer goes, so a task that needs the database opens a connection of its own.
202 Accepted: taken on, finished later
Some work is too slow for any caller to wait for, such as a recap of the month's picks that reads every pick and writes a report. The answer for that is 202 Accepted: "I've taken it on, and it will be done later". Its body says where the result will be:
@app.post("/recaps", status_code=202)
def make_recap(background_tasks: BackgroundTasks):
background_tasks.add_task(build_recap)
return {"detail": "The month's recap is on its way. Ask GET /recaps/latest for it in a few minutes."}
POST /recaps answers 202 Accepted at once:
{"detail":"The month's recap is on its way. Ask GET /recaps/latest for it in a few minutes."}
Use 201 when the thing was made before the answer, as the pick was, and 202 when it's still being made.
What a job queue adds
BackgroundTasks keeps its jobs in the server's memory. That's honest about what it's for:
- A stopped server loses its jobs. Ctrl+C waits for the jobs that are running, but a crash, a forced stop or a host that restarts the server loses every job still waiting, and nothing saved them.
- A failed job is never retried. The caller already has its 201, so nobody hears about the failure except the server's log.
- Heavy work slows the server, because the jobs share it with the requests.
A job queue is the full-size version: a separate program that keeps each job in a store of its own (often Redis), runs it in workers apart from the web server, and tries it again when it fails. Celery and RQ are the two you'll meet in Python projects. They're more to set up and run, so the rule of thumb is: BackgroundTasks for small, quick jobs you could afford to lose now and then, such as a chat message or a log entry; a job queue for work that must happen, such as charging a card or sending a receipt someone is owed.
Check yourself
2 questions to try on the lesson page.
So what
Answering first and doing the rest after keeps an API quick, and knowing that BackgroundTasks keeps its jobs only in memory tells you when the work deserves a real job queue instead.