Getting Started

In this section, we will get started and build our first GraphQL API using FastGraphQL.

Running your application

In this tutorial we will use two integrated components to create our GraphQL API, those are FastAPI and Ariadne.

We will use uvicorn to run the application:

$ uvicorn main:app --reload

My First GraphQL API

Let us create a file:

main.py
from fastapi import FastAPI
from fastgraphql import FastGraphQL
from fastgraphql.fastapi import make_ariadne_fastapi_router

app = FastAPI()
fast_graphql = FastGraphQL()


@fast_graphql.query()
def hello() -> str:
    return "Hello FastGraphQL!!!"


app.include_router(make_ariadne_fastapi_router(fast_graphql=fast_graphql))

In the same folder run:

$ uvicorn main:app --reload

Running uvicorn

main refers to the module main defined with main.py
app refers to the FastAPI application variable defined in main.py
--reload monitors changes and reload the application

Check it

Open your browser at http://127.0.0.1:8000/graphql/graphql.

Doing that you will see the GraphQL Playground where you can explore your GraphQL API.

Dissecting the code

Step 1: Importing

main.py
from fastapi import FastAPI
from fastgraphql import FastGraphQL
from fastgraphql.fastapi import make_ariadne_fastapi_router

app = FastAPI()
fast_graphql = FastGraphQL()


@fast_graphql.query()
def hello() -> str:
    return "Hello FastGraphQL!!!"


app.include_router(make_ariadne_fastapi_router(fast_graphql=fast_graphql))

FastGraphQL is a class that is the base for all GraphQL definitions and management of the API calls. Its instance and methods should be the starting point of defining your GraphQL API.

Step 2: Instantiating

main.py
from fastapi import FastAPI
from fastgraphql import FastGraphQL
from fastgraphql.fastapi import make_ariadne_fastapi_router

app = FastAPI()
fast_graphql = FastGraphQL()


@fast_graphql.query()
def hello() -> str:
    return "Hello FastGraphQL!!!"


app.include_router(make_ariadne_fastapi_router(fast_graphql=fast_graphql))

fast_graphql = FastGraphQL() is where everything start. The variable fast_graphql will be used across the code to define the complete GraphQL API

Customizations

The class initializer allows customizations to the complete GraphQL Schema generation. This will be covered in Global Customizations

Naming

The variable name fast_graphql was selected to reflect the class FastGraphQL, but it could have any selected name.

If you choose a different name remember to rename the reference in the annotation covered in the next section and everything will work as described in this documentation.

Choose variable names wisely.

Step 3: The First Query

main.py
from fastapi import FastAPI
from fastgraphql import FastGraphQL
from fastgraphql.fastapi import make_ariadne_fastapi_router

app = FastAPI()
fast_graphql = FastGraphQL()


@fast_graphql.query()
def hello() -> str:
    return "Hello FastGraphQL!!!"


app.include_router(make_ariadne_fastapi_router(fast_graphql=fast_graphql))

This section of the code is the most interesting part to understand at this point. Let us look into all details.

Annotating

Annotating a method with @fast_graphql.query() will tell FastGraphQL that this method should be handled as a resolver for a query. The query name will be the same as the method, in this case, hello.

Customizations

This method allows local customizations to the query schema generation. This will be covered in the Local Customizations

Method signature

The most important python feature FastGraphQL uses is type hinting and everything is based on that. Having said that, the method signature def hello() ->str:` can tell all necessary information to FastGraphQL, which in this case are:

method name: hello
return type: str

Type Hints

FastGraphQL is implemented under the assumption that all definitions, including methods, parameters and class attributes, have type hints annotations. More details on supported types can be found in the next section, Types

Step 3: Exposing the Schema

main.py
from fastapi import FastAPI
from fastgraphql import FastGraphQL
from fastgraphql.fastapi import make_ariadne_fastapi_router

app = FastAPI()
fast_graphql = FastGraphQL()


@fast_graphql.query()
def hello() -> str:
    return "Hello FastGraphQL!!!"


app.include_router(make_ariadne_fastapi_router(fast_graphql=fast_graphql))

Tearing this lines apart we have:

from fastgraphql.fastapi import make_ariadne_fastapi_router is importing from the FastAPI integration inside FastGraphQL, the method we will use to expose our implementation as a GraphQL API using Ariadne.
app.include_router(...) this is part of the FastAPI API and it includes a router returned by make_ariadne_fastapi_router(...). See FastAPI for more details on this method
make_ariadne_fastapi_router(...) is part of FastAPI and Ariadne integration. It generates an executable schema using Ariadne's API and returns a FastAPI router to expose the GraphQL API using the FastAPI application app.

GraphQL Schema

If you would include this line in the file

main.py
from fastapi import FastAPI
from fastgraphql import FastGraphQL
from fastgraphql.fastapi import make_ariadne_fastapi_router

app = FastAPI()
fast_graphql = FastGraphQL()


@fast_graphql.query()
def hello() -> str:
    return "Hello FastGraphQL!!!"


app.include_router(make_ariadne_fastapi_router(fast_graphql=fast_graphql))

print(fast_graphql.render())

and simply run with

python main.py

you will be able to inspect the generated GraphQL schema.

type Query {
    hello: String!
}

a very simple schema so far

.