Strawberry with FastAPI

This page assumes strawberry-graphql[fastapi] is already installed and that a uvicorn development server is available — both covered in Getting started with Python GraphQL. Every example below assumes the following imports are in scope:

A Strawberry type is a plain Python dataclass decorated with @strawberry.type; each attribute becomes a GraphQL field, with the Python type hint mapped onto the matching GraphQL scalar or object type. A method decorated with @strawberry.field becomes a computed field, resolved on demand rather than stored as data:

display_title above is a sync resolver — a plain method body, no async/await involved — appropriate for a field computed purely from data already in memory. The next section covers when to reach for async def instead. Scalars, enums, interfaces, unions, generics, and input types are covered in depth in Strawberry — schema and features; this page only introduces enough of the type system to build a runnable FastAPI integration.

Every Strawberry schema is assembled from up to three root types — Query is mandatory, Mutation and Subscription are added only if the API needs them — each a @strawberry.type whose fields are the schema’s top-level operations:

strawberry.Schema(…​) builds the executable schema from these roots; subscription= joins query= and mutation= once a Subscription root type exists (covered later on this page). The Query/Mutation split mirrors the language-agnostic model in Queries \& fields and Mutations — Strawberry does not change GraphQL’s read/write semantics, only how the roots are declared in Python.

A @strawberry.field-decorated method can be either a plain def or an async def; Strawberry’s execution engine awaits whichever resolvers declare themselves async and calls the rest synchronously, so the two styles mix freely across a single schema. Reach for async def whenever a resolver performs I/O — a database query, an HTTP call to another service, a DataLoader batch load — so that the ASGI event loop can service other requests (or other fields of the same query, executed concurrently) while the resolver waits:

Mixing a slow synchronous resolver into an otherwise async request path blocks the event loop for every other concurrent request, so a resolver doing blocking I/O (a synchronous database driver, a blocking HTTP client) should either be rewritten against an async driver or offloaded with asyncio.to_thread rather than left as a plain def. Execution \& resolvers covers how the execution engine schedules and awaits resolvers language-agnostically; this section only covers the Python sync/async split on top of it.

strawberry.fastapi.GraphQLRouter wraps a strawberry.Schema as a FastAPI APIRouter, handling the POST /graphql query/mutation endpoint, the GraphiQL IDE on GET, and (as covered further down) the WebSocket upgrade for subscriptions, all from one router mounted at a single prefix:

Because GraphQLRouter is a regular APIRouter, it composes with the rest of a FastAPI application exactly like any other router — other REST routes, middleware, and startup/shutdown events on the same app are unaffected, and nothing about mounting it requires the rest of the application to be GraphQL-aware. See Strawberry — FastAPI for the full integration reference, including the ASGI-level (non-FastAPI) mounting option for applications that only need the router’s underlying ASGI app.

Every resolver receives a strawberry.Info argument whose .context attribute is a place for the transport layer to hand resolvers whatever request-scoped state they need — the incoming request, a database session, the authenticated user. GraphQLRouter’s `context_getter parameter is itself a FastAPI dependency, which means it can declare Depends(…​) parameters of its own and FastAPI resolves them exactly as it would for a normal route handler, before the GraphQL request executes:

A resolver then reads info.context["db_session"] or info.context["current_user"] exactly like the recommended_books resolver did earlier. The dictionary shape above is the simplest option; a context_getter can instead return an instance of a class inheriting strawberry.fastapi.BaseContext, giving resolvers attribute access (info.context.current_user) instead of dictionary keys, and a natural place to add helper methods alongside the request-scoped data. Either way, the mechanism is the same: FastAPI’s own dependency injection graph runs once per request, and its results land in info.context for every resolver in that request to share.

GraphQLRouter serves an in-browser GraphQL IDE on GET requests to its mounted path by default, controlled by the graphql_ide parameter:

Passing None disables the IDE entirely, which most teams do once an environment moves from local development toward production — the IDE offers autocomplete and schema exploration against introspection, which is convenience during development rather than something a production deployment needs to expose. The three language-agnostic IDEs themselves (GraphiQL, Apollo Sandbox, and their historical predecessor GraphQL Playground) are introduced in Getting started with GraphQL.

A Subscription root type looks like Query/Mutation except each field is decorated @strawberry.subscription and returns an AsyncGenerator — the resolver body `yield`s a value each time the subscription should push an update to the client, rather than returning a single result:

GraphQLRouter serves this subscription over WebSocket by default, supporting both the legacy graphql-ws protocol id (implemented by the older subscriptions-transport-ws package, kept for backward compatibility with older clients) and the newer graphql-transport-ws protocol id (implemented by the actively maintained graphql-ws package) that current clients should prefer; both are negotiated automatically from the client’s requested Sec-WebSocket-Protocol header, with no extra configuration needed for the common case. Server-Sent Events is an HTTP-only alternative transport for subscriptions — useful where a WebSocket upgrade is impractical (some proxies, some serverless deployments) — enabled by opting a schema into the SSE protocol explicitly rather than being on by default alongside the WebSocket protocols.

Authentication for a subscription connection is handled differently from a query or mutation, because a WebSocket’s initial connection parameters (not an HTTP header set once per request) are where a client typically passes a token; GraphQLRouter exposes an on_ws_connect hook a server can override to inspect those parameters and raise a ConnectionRejectionError to refuse the connection before any subscription resolver runs. Subscriptions covers the subscription operation type and its WebSocket sub-protocols language-agnostically; see Strawberry — Subscriptions for the full Python reference, including cancellation handling and the ASGI/AIOHTTP/Django integrations beyond FastAPI.

Tying the pieces on this page together, a single GraphQL request over HTTP moves through GraphQLRouter, its context_getter, the schema’s execution engine, and the resolvers defined above, with DataLoader batching (covered in depth on Performance \& N+1) sitting between a resolver and the datastore it ultimately reads from:

This diagram is specific to the FastAPI + Strawberry integration on this page; the language-agnostic parse/validate/execute/respond lifecycle it sits inside of is covered once, as the canonical reference, in Getting started with GraphQL.

This page covered enough of Strawberry’s type system and FastAPI integration to run a working GraphQL server; three siblings go deeper on adjacent concerns: