Getting started¶

Introduction¶

What is GraphQL?¶

GraphQL is a query language for your API.

It provides a standard way to:

describe data provided by a server in a statically typed Schema
request data in a Query which exactly describes your data requirements and
receive data in a Response containing only the data you requested.

For an introduction to GraphQL and an overview of its concepts, please refer to the official GraphQL documentation.

What is Graphene?¶

Graphene is a library that provides tools to implement a GraphQL API in Python using a code-first approach.

Compare Graphene’s code-first approach to building a GraphQL API with schema-first approaches like Apollo Server (JavaScript) or Ariadne (Python). Instead of writing GraphQL Schema Definition Language (SDL), we write Python code to describe the data provided by your server.

Graphene is fully featured with integrations for the most popular web frameworks and ORMs. Graphene produces schemas that are fully compliant with the GraphQL spec and provides tools and patterns for building a Relay-Compliant API as well.

An example in Graphene¶

Let’s build a basic GraphQL schema to say “hello” and “goodbye” in Graphene.

When we send a Query requesting only one Field, hello, and specify a value for the name Argument...

{
  hello(name: "friend")
}

...we would expect the following Response containing only the data requested (the goodbye field is not resolved).

{
  "data": {
    "hello": "Hello friend!"
  }
}

Requirements¶

Python (2.7, 3.4, 3.5, 3.6, pypy)
Graphene (3.0)

Project setup¶

pip install "graphene>=3.0"

Creating a basic Schema¶

In Graphene, we can define a simple schema using the following code:

from graphene import ObjectType, String, Schema

class Query(ObjectType):
    # this defines a Field `hello` in our Schema with a single Argument `name`
    hello = String(name=String(default_value="stranger"))
    goodbye = String()

    # our Resolver method takes the GraphQL context (root, info) as well as
    # Argument (name) for the Field and returns data for the query Response
    def resolve_hello(root, info, name):
        return f'Hello {name}!'

    def resolve_goodbye(root, info):
        return 'See ya!'

schema = Schema(query=Query)

A GraphQL Schema describes each Field in the data model provided by the server using scalar types like String, Int and Enum and compound types like List and Object. For more details refer to the Graphene Types Reference.

Our schema can also define any number of Arguments for our Fields. This is a powerful way for a Query to describe the exact data requirements for each Field.

For each Field in our Schema, we write a Resolver method to fetch data requested by a client’s Query using the current context and Arguments. For more details, refer to this section on Resolvers.

Schema Definition Language (SDL)¶

In the GraphQL Schema Definition Language, we could describe the fields defined by our example code as shown below.

type Query {
  hello(name: String = "stranger"): String
  goodbye: String
}

Further examples in this documentation will use SDL to describe schema created by ObjectTypes and other fields.

Querying¶

Then we can start querying our Schema by passing a GraphQL query string to execute:

# we can query for our field (with the default argument)
query_string = '{ hello }'
result = schema.execute(query_string)
print(result.data['hello'])
# "Hello stranger!"

# or passing the argument in the query
query_with_argument = '{ hello(name: "GraphQL") }'
result = schema.execute(query_with_argument)
print(result.data['hello'])
# "Hello GraphQL!"

Next steps¶

Congrats! You got your first Graphene schema working!

Normally, we don’t need to directly execute a query string against our schema as Graphene provides many useful Integrations with popular web frameworks like Flask and Django. Check out Integrations for more information on how to get started serving your GraphQL API.

Previous: Graphene Next: Types Reference

Execution¶

Documentation