Graphene – GraphQL em Python: guia completo para APIs modernas

Introdução ao GraphQL e Graphene

GraphQL é uma linguagem de consulta moderna para APIs e um ambiente de execução, desenvolvido pelo Facebook em 2012 para resolver problemas das APIs REST tradicionais. Graphene é uma poderosa biblioteca Python que oferece uma implementação completa da especificação GraphQL, com suporte a schemas tipados, mutações e integração com sistemas ORM populares.

O que é GraphQL e por que usá-lo

GraphQL representa uma abordagem declarativa para obter dados, onde o cliente descreve exatamente quais dados precisa. Diferente do REST, onde o servidor define a estrutura da resposta, o GraphQL permite que o cliente monte suas próprias consultas e receba apenas os dados necessários.

Principais vantagens do GraphQL sobre REST

Ponto único de entrada

GraphQL usa um único endpoint URL para todas as operações, simplificando a arquitetura da API e eliminando a necessidade de versionamento via URL.

Flexibilidade nas consultas

O cliente define a estrutura da resposta, solicitando apenas os campos e dados relacionados que precisa.

Eliminação de redundância de dados

Os problemas de over-fetching (receber dados em excesso) e under-fetching (falta de dados) são resolvidos no nível da consulta.

Combinação de dados relacionados

É possível obter dados de várias entidades relacionadas em uma única consulta, reduzindo o número de chamadas ao servidor.

Tipagem forte

O schema GraphQL é estaticamente tipado, garantindo validação de consultas e autocompletar na IDE.

Documentação automática

O schema serve como documentação viva da API, acessível através de introspecção.

Instalação e configuração do Graphene

Instalação básica

pip install graphene

Integração com frameworks web

Para Flask:

pip install flask-graphql

Para Django:

pip install graphene-django

Para FastAPI:

pip install starlette-graphene3

Integração com bancos de dados

Para SQLAlchemy:

pip install graphene-sqlalchemy

Para Django ORM:

pip install graphene-django

Criando um servidor GraphQL básico

Exemplo com Flask

from flask import Flask
from flask_graphql import GraphQLView
import graphene

app = Flask(__name__)

class Query(graphene.ObjectType):
    hello = graphene.String(name=graphene.String(default_value="mundo"))
    
    def resolve_hello(self, info, name):
        return f"Olá, {name}!"

schema = graphene.Schema(query=Query)

app.add_url_rule('/graphql', view_func=GraphQLView.as_view(
    'graphql', 
    schema=schema, 
    graphiql=True  # Ativa a interface GraphiQL
))

if __name__ == '__main__':
    app.run(debug=True)

Exemplo com Django

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'graphene_django',
    'myapp',
]

GRAPHENE = {
    'SCHEMA': 'myproject.schema.schema'
}

# urls.py
from django.urls import path
from graphene_django.views import GraphQLView

urlpatterns = [
    path('graphql/', GraphQLView.as_view(graphiql=True)),
]

Definindo tipos e schemas no Graphene

Criando tipos personalizados

import graphene

class User(graphene.ObjectType):
    id = graphene.ID()
    name = graphene.String()
    email = graphene.String()
    age = graphene.Int()
    is_active = graphene.Boolean()
    
    # Campos calculados
    full_name = graphene.String()
    
    def resolve_full_name(self, info):
        return f"{self.first_name} {self.last_name}"

class Post(g