API GraphQL con C#: Tutorial práctico paso a paso

Introducción: Por qué GraphQL y C# son la pareja ideal

El desarrollo web moderno requiere API flexibles y eficientes. REST API, a pesar de su popularidad, a menudo sufre de over-fetching (obtener datos innecesarios) y under-fetching (necesidad de múltiples solicitudes para obtener información completa). GraphQL resuelve estos problemas permitiendo al cliente solicitar solo lo que necesita en una sola consulta.

En este tutorial crearemos una API GraphQL completa en C# utilizando la biblioteca Hot Chocolate, la implementación más popular de GraphQL para .NET. Aprenderá a configurar el servidor, definir el esquema, implementar consultas (queries), mutaciones (mutations) y suscripciones (subscriptions). Todos los ejemplos de código serán prácticos y listos para usar.

¿Para quién es este material? Para desarrolladores .NET que quieran dominar GraphQL y para aquellos que buscan una alternativa a REST. Se recomiendan conocimientos básicos de C# y ASP.NET Core, aunque no son obligatorios.

1. Configuración del proyecto e instalación de Hot Chocolate

Creación del proyecto ASP.NET Core

Empecemos creando un nuevo proyecto. Abra la terminal o línea de comandos y ejecute:

dotnet new web -n GraphQLDemo\ncd GraphQLDemo

Ahora instalemos el paquete Hot Chocolate:

dotnet add package HotChocolate.AspNetCore\ndotnet add package HotChocolate.AspNetCore.Playground

El paquete HotChocolate.AspNetCore añade middleware para procesar solicitudes GraphQL, y HotChocolate.AspNetCore.Playground proporciona un IDE integrado (GraphQL Playground) para pruebas.

Configuración de Startup

Edite el archivo Program.cs (o Startup.cs para .NET 5 y versiones anteriores). Añadamos la configuración básica:

var builder = WebApplication.CreateBuilder(args);\n\n// Añadimos servicios GraphQL\nbuilder.Services\n    .AddGraphQLServer()\n    .AddQueryType<Query>()\n    .AddMutationType<Mutation>(); // lo añadiremos más adelante\n\nvar app = builder.Build();\n\n// Añadimos middleware\napp.UseRouting();\napp.MapGraphQL(); // endpoint /graphql\napp.MapGraphQLPlayground(); // Playground disponible en /playground\n\napp.Run();

Tenga en cuenta: Query y Mutation son las clases que crearemos a continuación. Por ahora dejaremos solo Query.

2. Creación del modelo de datos y primera consulta (Query)

Modelo Book

Creemos un modelo simple de libro. Añada el archivo Models/Book.cs:

namespace GraphQLDemo.Models;\n\npublic class Book\n{\n    public int Id { get; set; }\n    public string Title { get; set; } = string.Empty;\n    public string Author { get; set; } = string.Empty;\n    public int Year { get; set; }\n    public decimal Price { get; set; }\n}

Clase Query

Ahora creemos la clase Query, que contendrá los métodos para obtener datos. Añada el archivo GraphQL/Query.cs:

using GraphQLDemo.Models;\n\nnamespace GraphQLDemo.GraphQL;\n\npublic class Query\n{\n    // Almacenamiento temporal de datos (en un proyecto real sería una BD)\n    private static readonly List<Book> Books = new()\n    {\n        new Book { Id = 1, Title = "Guerra y paz", Author = "León Tolstói", Year = 1869, Price = 29.99m },\n        new Book { Id = 2, Title = "Crimen y castigo", Author = "Fiódor Dostoyevski", Year = 1866, Price = 24.99m },\n        new Book { Id = 3, Title = "El maestro y Margarita", Author = "Mijaíl Bulgákov", Year = 1967, Price = 19.99m }\n    };\n\n    // Consulta: obtener todos los libros\n    public IQueryable<Book> GetBooks() => Books.AsQueryable();\n\n    // Consulta: obtener un libro por ID\n    public Book? GetBookById(int id) => Books.FirstOrDefault(b => b.Id == id);\n}

Los métodos que devuelven datos se denominan resolvers. Hot Chocolate automáticamente