Sebastián Ramírez
4 years ago
committed by
GitHub
GitHub
8 changed files with 56 additions and 39 deletions
@ -1,44 +1,56 @@ |
|||
# GraphQL |
|||
|
|||
**FastAPI** has optional support for GraphQL (provided by Starlette directly), using the `graphene` library. |
|||
As **FastAPI** is based on the **ASGI** standard, it's very easy to integrate any **GraphQL** library also compatible with ASGI. |
|||
|
|||
You can combine normal FastAPI *path operations* with GraphQL on the same application. |
|||
|
|||
## Import and use `graphene` |
|||
!!! tip |
|||
**GraphQL** solves some very specific use cases. |
|||
|
|||
GraphQL is implemented with Graphene, you can check <a href="https://docs.graphene-python.org/en/latest/quickstart/" class="external-link" target="_blank">Graphene's docs</a> for more details. |
|||
It has **advantages** and **disadvantages** when compared to common **web APIs**. |
|||
|
|||
Import `graphene` and define your GraphQL data: |
|||
Make sure you evaluate if the **benefits** for your use case compensate the **drawbacks**. 🤓 |
|||
|
|||
```Python hl_lines="1 6-10" |
|||
{!../../../docs_src/graphql/tutorial001.py!} |
|||
``` |
|||
## GraphQL Libraries |
|||
|
|||
Here are some of the **GraphQL** libraries that have **ASGI** support. You could use them with **FastAPI**: |
|||
|
|||
* <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a> 🍓 |
|||
* With <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">docs for FastAPI</a> |
|||
* <a href="https://ariadnegraphql.org/" class="external-link" target="_blank">Ariadne</a> |
|||
* With <a href="https://ariadnegraphql.org/docs/starlette-integration" class="external-link" target="_blank">docs for Starlette</a> (that also apply to FastAPI) |
|||
* <a href="https://tartiflette.io/" class="external-link" target="_blank">Tartiflette</a> |
|||
* With <a href="https://tartiflette.github.io/tartiflette-asgi/" class="external-link" target="_blank">Tartiflette ASGI</a> to provide ASGI integration |
|||
* <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a> |
|||
* With <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a> |
|||
|
|||
## GraphQL with Strawberry |
|||
|
|||
If you need or want to work with **GraphQL**, <a href="https://strawberry.rocks/" class="external-link" target="_blank">**Strawberry**</a> is the **recommended** library as it has the design closest to **FastAPI's** design, it's all based on **type annotations**. |
|||
|
|||
## Add Starlette's `GraphQLApp` |
|||
Depending on your use case, you might prefer to use a different library, but if you asked me, I would probably suggest you try **Strawberry**. |
|||
|
|||
Then import and add Starlette's `GraphQLApp`: |
|||
Here's a small preview of how you could integrate Strawberry with FastAPI: |
|||
|
|||
```Python hl_lines="3 14" |
|||
```Python hl_lines="3 22 25-26" |
|||
{!../../../docs_src/graphql/tutorial001.py!} |
|||
``` |
|||
|
|||
!!! info |
|||
Here we are using `.add_route`, that is the way to add a route in Starlette (inherited by FastAPI) without declaring the specific operation (as would be with `.get()`, `.post()`, etc). |
|||
You can learn more about Strawberry in the <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry documentation</a>. |
|||
|
|||
## Check it |
|||
And also the docs about <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">Strawberry with FastAPI</a>. |
|||
|
|||
Run it with Uvicorn and open your browser at <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>. |
|||
## Older `GraphQLApp` from Starlette |
|||
|
|||
You will see GraphiQL web user interface: |
|||
Previous versions of Starlette included a `GraphQLApp` class to integrate with <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>. |
|||
|
|||
<img src="/img/tutorial/graphql/image01.png"> |
|||
It was deprecated from Starlette, but if you have code that used it, you can easily **migrate** to <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>, that covers the same use case and has an **almost identical interface**. |
|||
|
|||
## More details |
|||
!!! tip |
|||
If you need GraphQL, I still would recommend you check out <a href="https://strawberry.rocks/" class="external-link" target="_blank">Strawberry</a>, as it's based on type annotations instead of custom classes and types. |
|||
|
|||
For more details, including: |
|||
## Learn More |
|||
|
|||
* Accessing request information |
|||
* Adding background tasks |
|||
* Using normal or async functions |
|||
You can learn more about **GraphQL** in the <a href="https://graphql.org/" class="external-link" target="_blank">official GraphQL documentation</a>. |
|||
|
|||
check the official <a href="https://www.starlette.io/graphql/" class="external-link" target="_blank">Starlette GraphQL docs</a>. |
|||
You can also read more about each those libraries described above in their links. |
|||
|
|||
@ -1,14 +1,26 @@ |
|||
import graphene |
|||
import strawberry |
|||
from fastapi import FastAPI |
|||
from starlette.graphql import GraphQLApp |
|||
from strawberry.asgi import GraphQL |
|||
|
|||
|
|||
class Query(graphene.ObjectType): |
|||
hello = graphene.String(name=graphene.String(default_value="stranger")) |
|||
@strawberry.type |
|||
class User: |
|||
name: str |
|||
age: int |
|||
|
|||
def resolve_hello(self, info, name): |
|||
return "Hello " + name |
|||
|
|||
@strawberry.type |
|||
class Query: |
|||
@strawberry.field |
|||
def user(self) -> User: |
|||
return User(name="Patrick", age=100) |
|||
|
|||
|
|||
schema = strawberry.Schema(query=Query) |
|||
|
|||
|
|||
graphql_app = GraphQL(schema) |
|||
|
|||
app = FastAPI() |
|||
app.add_route("/", GraphQLApp(schema=graphene.Schema(query=Query))) |
|||
app.add_route("/graphql", graphql_app) |
|||
app.add_websocket_route("/graphql", graphql_app) |
|||
|
|||
Loading…
Reference in new issue