Durante años trabajé exclusivamente con REST. Funciona, escala, es predecible — no tenía razones para cambiar. Hasta que me tocó construir una API para una app móvil que consumía cinco endpoints distintos para armar una sola pantalla. Ahí entendí el problema de under-fetching en carne propia. Empecé a explorar GraphQL y, en el ecosistema .NET, el camino lleva inevitablemente a Hot Chocolate. En este artículo cuento cómo funciona, con ejemplos que van desde la configuración básica hasta DataLoaders y Subscriptions en tiempo real.
¿Qué es GraphQL y por qué importa?
GraphQL es un lenguaje de consulta para APIs que expone un único endpoint. El cliente define exactamente qué datos necesita — ni más, ni menos. Esto resuelve dos problemas clásicos de REST:
- Over-fetching: el endpoint devuelve 30 campos y el cliente usa 5.
- Under-fetching: para armar una pantalla necesitás llamar a 4 endpoints distintos.
Hot Chocolate es la implementación de GraphQL para .NET más completa y activa que existe. Es modular, se integra nativamente con ASP.NET Core y Entity Framework Core, y su enfoque Code-First (definir el esquema desde clases C#) hace que el onboarding sea natural para cualquier desarrollador .NET.
1. Configuración Inicial y Queries Básicas
El punto de entrada: registrar el servidor GraphQL en el contenedor de DI y mapear el endpoint. Una Query en GraphQL es el equivalente a GET en REST — define qué datos pueden leer los clientes.
// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddGraphQLServer()
.AddQueryType<Query>();
var app = builder.Build();
app.MapGraphQL(); // Endpoint por defecto: /graphql
app.Run();
// Query.cs
public class Query
{
public string GetHolaMundo() => "¡Hola desde Hot Chocolate!";
public Usuario GetUsuarioActual() => new Usuario { Id = 1, Nombre = "Admin" };
}
public class Usuario
{
public int Id { get; set; }
public string Nombre { get; set; }
}Hot Chocolate genera automáticamente el esquema GraphQL a partir de las clases C#. Al navegar a /graphql, tenés acceso al playground interactivo Banana Cake Pop donde podés explorar y ejecutar queries.
2. Relaciones Anidadas con Projections y EF Core
Acá empieza la magia real. El atributo [UseProjection] intercepta la query GraphQL del cliente y genera dinámicamente el SELECT SQL correspondiente. Si el cliente pide solo nombre y titulo, la base de datos devuelve solo esas columnas. Sin traer entidades completas a memoria.
public class Autor
{
public int Id { get; set; }
public string Nombre { get; set; }
public ICollection<Libro> Libros { get; set; }
}
public class Libro
{
public int Id { get; set; }
public string Titulo { get; set; }
public int AutorId { get; set; }
}
public class Query
{
[UseProjection]
public IQueryable<Autor> GetAutores([Service] AppDbContext context)
=> context.Autores;
}
/* Query del cliente — una sola petición, datos exactos:
query {
autores {
nombre
libros {
titulo
}
}
}
*/3. Filtros y Ordenamiento Dinámico
Con [UseFiltering] y [UseSorting], el cliente puede enviar argumentos complejos de búsqueda que Hot Chocolate traduce automáticamente a expresiones LINQ. El orden de los atributos importa: primero Projections, luego Filtering, luego Sorting.
// Program.cs — registrar las capacidades
builder.Services.AddGraphQLServer()
.AddFiltering()
.AddSorting();
// Query.cs
public class Query
{
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<Libro> GetLibros([Service] AppDbContext context)
=> context.Libros;
}
/* Query del cliente con filtro y ordenamiento:
query {
libros(
where: { titulo: { contains: "GraphQL" } }
order: [ { id: DESC } ]
) {
id
titulo
}
}
*/Todo esto se traduce a una sola query SQL optimizada. Sin código adicional en el servidor.
4. Mutations: Escritura de Datos
Las Mutations son el equivalente a POST/PUT/DELETE en REST. Lo interesante es que devuelven un tipo de dato (Payload), permitiendo al cliente mutar y consultar el nuevo estado en la misma operación.
// Program.cs
builder.Services.AddGraphQLServer()
.AddMutationType<Mutation>();
// Mutation.cs
public class Mutation
{
public async Task<LibroPayload> CrearLibroAsync(
CrearLibroInput input,
[Service] AppDbContext context)
{
var nuevoLibro = new Libro
{
Titulo = input.Titulo,
AutorId = input.AutorId
};
context.Libros.Add(nuevoLibro);
await context.SaveChangesAsync();
return new LibroPayload(nuevoLibro);
}
}
public record CrearLibroInput(string Titulo, int AutorId);
public record LibroPayload(Libro Libro);
/* Mutation del cliente — crea y consulta en una sola operación:
mutation {
crearLibro(input: { titulo: "Mastering Hot Chocolate", autorId: 1 }) {
libro {
id
titulo
}
}
}
*/5. DataLoaders: Eliminando el Problema N+1
El talón de Aquiles de cualquier implementación GraphQL ingenua es el problema N+1: si consultás 10 libros y cada libro necesita resolver su autor, terminás con 1 query para los libros + 10 queries individuales para los autores = 11 queries en total. Con un dataset real de 1000 libros, eso es un desastre.
Los DataLoaders resuelven esto agrupando todas las peticiones de autores en un solo lote y ejecutándolas en una única query a la base de datos, con caché automático por ciclo de vida de la petición.
public class AutorBatchDataLoader : BatchDataLoader<int, Autor>
{
private readonly AppDbContext _dbContext;
public AutorBatchDataLoader(
IBatchScheduler batchScheduler,
DataLoaderOptions options,
AppDbContext dbContext)
: base(batchScheduler, options)
{
_dbContext = dbContext;
}
protected override async Task<IReadOnlyDictionary<int, Autor>> LoadBatchAsync(
IReadOnlyList<int> keys,
CancellationToken cancellationToken)
{
// 1000 libros = 1 sola query con WHERE Id IN (...)
return await _dbContext.Autores
.Where(a => keys.Contains(a.Id))
.ToDictionaryAsync(a => a.Id, cancellationToken);
}
}
// Extensión de tipo para resolver el autor de cada libro usando el DataLoader
[ExtendObjectType(typeof(Libro))]
public class LibroExtensions
{
public async Task<Autor> GetAutorAsync(
[Parent] Libro libro,
AutorBatchDataLoader dataLoader,
CancellationToken cancellationToken)
=> await dataLoader.LoadAsync(libro.AutorId, cancellationToken);
[GraphQLName("tituloEnMayusculas")]
public string GetTituloMayusculas([Parent] Libro libro)
=> libro.Titulo.ToUpper();
}
// Program.cs — registrar la extensión
// builder.Services.AddGraphQLServer().AddType<LibroExtensions>();6. Subscriptions: Datos en Tiempo Real
Esto es lo que REST no puede hacer de forma nativa: el cliente se suscribe a un evento y el servidor le notifica automáticamente cuando ocurre. Hot Chocolate implementa Subscriptions sobre WebSockets, lo que es ideal para notificaciones en vivo, dashboards en tiempo real o chats.
// Program.cs — habilitar WebSockets y Subscriptions
app.UseWebSockets();
builder.Services.AddGraphQLServer()
.AddSubscriptionType<Subscription>()
.AddInMemorySubscriptions(); // Para un solo servidor; en cluster usar Redis
// Subscription.cs
public class Subscription
{
[Subscribe]
[Topic("LibroCreado")]
public Libro OnLibroCreado([EventMessage] Libro libro) => libro;
}
// En la Mutation, publicar el evento al crear un libro
public class Mutation
{
public async Task<LibroPayload> CrearLibroAsync(
CrearLibroInput input,
[Service] AppDbContext context,
[Service] ITopicEventSender eventSender,
CancellationToken cancellationToken)
{
var nuevoLibro = new Libro { Titulo = input.Titulo, AutorId = input.AutorId };
context.Libros.Add(nuevoLibro);
await context.SaveChangesAsync(cancellationToken);
// Notificar a todos los clientes suscritos
await eventSender.SendAsync("LibroCreado", nuevoLibro, cancellationToken);
return new LibroPayload(nuevoLibro);
}
}
/* Suscripción del cliente (WebSocket):
subscription {
onLibroCreado {
id
titulo
}
}
*/La primera vez que vi esto funcionar en un dashboard en tiempo real, conectado a una app móvil y una web simultáneamente, entendí por qué GraphQL cambió la forma en que pensamos las APIs.
GraphQL vs. REST: ¿Cuándo usar cada uno?
No es una competencia — son herramientas para contextos distintos. Mi criterio:
- Usá GraphQL cuando: tenés múltiples clientes (web, móvil, terceros) con necesidades de datos distintas, o cuando necesitás tiempo real con Subscriptions.
- Usá REST cuando: la API es pública y necesita ser consumida por herramientas genéricas (cURL, Postman básico, integraciones externas simples), o cuando el equipo no tiene experiencia con GraphQL y el deadline no da margen.
En proyectos complejos, también conviven: REST para endpoints públicos y webhooks, GraphQL para el frontend propio.
Conclusión
Hot Chocolate es, en mi opinión, la implementación más completa de GraphQL en cualquier ecosistema. La integración con EF Core, los DataLoaders para resolver N+1, las Subscriptions sobre WebSockets y el enfoque Code-First lo hacen una opción sólida para proyectos empresariales en .NET.
Si venís de REST y nunca probaste GraphQL, el primer paso es levantar un proyecto con la configuración básica y explorar el playground Banana Cake Pop. La curva de aprendizaje inicial es real, pero se amortiza rápido en proyectos con múltiples clientes o necesidades de datos complejas.
¿Tenés dudas sobre cómo migrar una API REST existente a GraphQL o cómo manejar autenticación y autorización en el esquema? Dejalo en los comentarios.