Graphene: GraphQL en Python – Guía completa y ejemplos

Introducción a GraphQL y Graphene

GraphQL es un lenguaje de consulta moderno para APIs y un entorno de ejecución, desarrollado por Facebook en 2012 para resolver los problemas de las APIs REST tradicionales. Graphene es una potente biblioteca de Python que proporciona una implementación completa de la especificación GraphQL, con soporte para esquemas tipados, mutaciones e integración con sistemas ORM populares.

¿Qué es GraphQL y por qué es necesario?

GraphQL representa un enfoque declarativo para obtener datos, donde el cliente describe exactamente qué datos necesita. A diferencia de REST, donde el servidor define la estructura de la respuesta, GraphQL permite al cliente formar sus propias consultas y obtener únicamente los datos que requiere.

Ventajas clave de GraphQL frente a REST

Punto de entrada único

GraphQL utiliza un único endpoint URL para todas las operaciones, lo que simplifica la arquitectura de la API y elimina la necesidad de versionado a través de la URL.

Flexibilidad en las consultas

El cliente define la estructura de la respuesta, solicitando solo los campos necesarios y los datos relacionados.

Eliminación de la redundancia de datos

Los problemas de over-fetching (obtener datos de más) y under-fetching (falta de datos) se resuelven a nivel de consulta.

Combinación de datos relacionados

Posibilidad de obtener datos de múltiples entidades relacionadas en una sola consulta, lo que reduce el número de solicitudes al servidor.

Tipado estricto

El esquema de GraphQL está tipado estáticamente, lo que garantiza la validación de consultas y el autocompletado en el IDE.

Documentación automática

El esquema sirve como documentación viva de la API, accesible mediante introspección.

Instalación y configuración de Graphene

Instalación básica

pip install graphene

Integración con frameworks web

Para Flask:

pip install flask-graphql

Para Django:

pip install graphene-django

Para FastAPI:

pip install starlette-graphene3

Integración con bases de datos

Para SQLAlchemy:

pip install graphene-sqlalchemy

Para Django ORM:

pip install graphene-django

Creación de un servidor GraphQL básico

Ejemplo con 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"¡Hola, {name}!"

schema = graphene.Schema(query=Query)

app.add_url_rule('/graphql', view_func=GraphQLView.as_view(
    'graphql', 
    schema=schema, 
    graphiql=True  # Habilita la interfaz GraphiQL
))

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

Ejemplo con 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)),
]

Definición de tipos y esquemas en Graphene

Creación de 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