GraphQL é uma linguagem de consulta para APIs desenvolvida pelo Facebook. Ela permite que o cliente peça exatamente os dados que precisa. Primeiramente, isso elimina o problema de over-fetching do REST. Por exemplo, um cliente pode solicitar apenas nome e email de um usuário. Além disso, uma única requisição GraphQL busca dados de múltiplos recursos. A voz passiva é usada aqui: “os esquemas são definidos usando tipos e campos”. Quando utilizar GraphQL? Em aplicações com interfaces complexas. Também quando o time frontend e backend são separados. Graphene é a biblioteca principal para GraphQL em Python. Ela integra-se bem com Django, SQLAlchemy e outros ORMs. Vamos explorar conceitos, implementação e casos de uso. Três subtítulos guiarão você pelo mundo GraphQL. Ao final, você construirá sua primeira API GraphQL completa.
Conceitos fundamentais do graphql
GraphQL tem três operações principais: query, mutation e subscription. Query busca dados (equivalente ao GET do REST). Mutation altera dados (POST, PUT, DELETE). Subscription recebe dados em tempo real (WebSockets). Cada operação é definida em um esquema com tipos. Tipos podem ser escalares (String, Int) ou objetos complexos. A voz passiva é aplicada: “as relações entre tipos são declaradas explicitamente”. Exemplo de um esquema GraphQL simples:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
# Esquema GraphQL (linguagem de definição de esquema) type Usuario { id: ID! nome: String! email: String! posts: [Post!]! } type Post { id: ID! titulo: String! conteudo: String! autor: Usuario! } type Query { usuario(id: ID!): Usuario usuarios: [Usuario!]! post(id: ID!): Post posts: [Post!]! } type Mutation { criarUsuario(nome: String!, email: String!): Usuario! criarPost(titulo: String!, conteudo: String!, autorId: ID!): Post! } |
O cliente pode fazer consultas como:
{ usuario(id: 1) { nome email posts { titulo } } }.
Isso retorna apenas os campos solicitados, nada mais.
A fórmula de economia de dados é:
\(E = 1 – \frac{T_{\text{GraphQL}}}{T_{\text{REST}}}\)
Onde T representa o tamanho dos dados transferidos.
GraphQL pode economizar até 70% de tráfego em aplicações ricas.
Implementando graphql com graphene e django
Graphene é a biblioteca padrão para GraphQL em Python.
Ela funciona com Django, Flask, FastAPI e SQLAlchemy.
Primeiro, instale com pip install graphene graphene-django.
Depois, defina os tipos (Type) e as queries (Query).
Quando usar Graphene? Em projetos Django que exigem flexibilidade.
Também em APIs públicas onde clientes têm necessidades diversas.
Exemplo completo de API GraphQL com Django:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
# models.py (Django) from django.db import models class Autor(models.Model): nome = models.CharField(max_length=100) email = models.EmailField(unique=True) class Livro(models.Model): titulo = models.CharField(max_length=200) ano = models.IntegerField() autor = models.ForeignKey(Autor, on_delete=models.CASCADE, related_name='livros') # schema.py (GraphQL) import graphene from graphene_django import DjangoObjectType from .models import Autor, Livro class AutorType(DjangoObjectType): class Meta: model = Autor fields = ('id', 'nome', 'email', 'livros') class LivroType(DjangoObjectType): class Meta: model = Livro fields = ('id', 'titulo', 'ano', 'autor') class Query(graphene.ObjectType): todos_autores = graphene.List(AutorType) autor_por_id = graphene.Field(AutorType, id=graphene.Int(required=True)) livros_por_ano = graphene.List(LivroType, ano=graphene.Int(required=True)) def resolve_todos_autores(self, info): return Autor.objects.all() def resolve_autor_por_id(self, info, id): try: return Autor.objects.get(id=id) except Autor.DoesNotExist: return None def resolve_livros_por_ano(self, info, ano): return Livro.objects.filter(ano=ano) class CriarAutor(graphene.Mutation): class Arguments: nome = graphene.String(required=True) email = graphene.String(required=True) autor = graphene.Field(AutorType) def mutate(self, info, nome, email): autor = Autor.objects.create(nome=nome, email=email) return CriarAutor(autor=autor) class Mutation(graphene.ObjectType): criar_autor = CriarAutor.Field() schema = graphene.Schema(query=Query, mutation=Mutation) # urls.py (configuração do endpoint GraphQL) from django.urls import path from graphene_django.views import GraphQLView from .schema import schema urlpatterns = [ path('graphql/', GraphQLView.as_view(graphiql=True, schema=schema)), ] |
Acesse /graphql/ no navegador para ver o GraphiQL.
Essa interface interativa permite testar consultas e mutações.
O GraphQL playground é uma das maiores vantagens da tecnologia.
GraphQL vs. rest: quando escolher cada um
REST é mais simples e adequado para APIs padrão. GraphQL é mais flexível e eficiente para clientes variados. Quando escolher GraphQL? Em aplicações com muitos recursos relacionados. Por exemplo, dashboards, aplicações móveis ou feeds de redes sociais. REST é melhor para APIs públicas simples e caching em CDN. GraphQL tem curva de aprendizado mais íngreme que REST. A voz passiva é usada: “as decisões de escolha são baseadas no contexto”. Graphene é excelente, mas a comunidade é menor que a do DRF. Para projetos pequenos, REST ainda é mais prático. Para sistemas complexos com frontend exigente, GraphQL brilha. Combine ambos: use REST para operações simples e GraphQL para consultas complexas. Comece com REST e migre partes específicas para GraphQL quando necessário. GraphQL não é bala de prata, mas é uma ferramenta poderosa. Experimente Graphene em seu próximo projeto Django. Você nunca mais vai querer criar múltiplos endpoints REST.