API GraphQL con C#: tutorial paso a paso para desarrolladores .NET

Introducción a GraphQL en la plataforma .NET

GraphQL es un lenguaje de consultas para API que permite a los clientes obtener solo los datos que realmente necesitan. A diferencia de REST, donde la estructura de la respuesta está rígidamente definida por el servidor, GraphQL permite formar consultas de manera flexible. En este tutorial crearemos una API GraphQL completa en C# utilizando el framework Hot Chocolate, la solución más popular para .NET.

Recorreremos el camino desde la instalación hasta la creación de consultas complejas con mutaciones y suscripciones. El artículo está dirigido a desarrolladores familiarizados con los fundamentos de C# y ASP.NET Core.

1. Configuración del proyecto e instalación de dependencias

Para comenzar, crearemos un nuevo proyecto ASP.NET Core. Puedes usar Visual Studio, Rider o la línea de comandos.

dotnet new web -n GraphQLDemocd GraphQLDemo

Ahora instalaremos el paquete Hot Chocolate, la herramienta principal para trabajar con GraphQL en .NET:

dotnet add package HotChocolate.AspNetCore

Adicionalmente, para trabajar con consultas a través de GraphQL IDE (Banana Cake Pop), instalaremos:

dotnet add package HotChocolate.AspNetCore.Playground

1.1 Configuración básica de Program.cs

Abre el archivo Program.cs y configura los servicios:

var builder = WebApplication.CreateBuilder(args);

builder.Services    .AddGraphQLServer()    .AddQueryType<Query>();

var app = builder.Build();

app.MapGraphQL();

app.Run();

Observa: registramos Query — este es nuestro tipo raíz para la lectura de datos. Por ahora está vacío, pero lo llenaremos.

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

GraphQL trabaja con tipos. Crearemos un modelo simple Book:

public class Book{    public int Id { get; set; }    public string Title { get; set; }    public string Author { get; set; }    public int Year { get; set; }}

Ahora definimos la clase Query, que devolverá los datos:

public class Query{    private static List<Book> _books = new()    {        new Book { Id = 1, Title = "1984", Author = "George Orwell", Year = 1949 },        new Book { Id = 2, Title = "Clean Code", Author = "Robert C. Martin", Year = 2008 }    };

    public IQueryable<Book> GetBooks() => _books.AsQueryable();

    public Book? GetBookById(int id) => _books.FirstOrDefault(b => b.Id == id);}

Ejecuta la aplicación y abre http://localhost:5000/graphql. Verás Banana Cake Pop, el IDE integrado para probar consultas. Intenta ejecutar:

{  books {    title    author  }}

Obtendrás solo los campos que solicitaste — en eso radica el poder de GraphQL.

3. Mutaciones para modificar datos

Las mutaciones son el equivalente de POST/PUT/DELETE en REST. Permiten modificar datos en el servidor. Añadiremos la posibilidad de agregar nuevos libros.

3.1 Definición del tipo de entrada

Crearemos una clase para los datos de entrada de la mutación:

public class AddBookInput{    public string Title { get; set; }    public string Author { get; set; }    public int Year { get; set; }}

3.2 Implementación de la mutación

Añadimos la clase Mutation:

public class Mutation{    private static List<Book> _books = new()    {        new Book { Id = 1, Title = "1984", Author = "George Orwell", Year = 1949 },        new Book { Id = 2, Title = "Clean Code", Author = "Robert C. Martin", Year = 2008 }    };

    public Book AddBook(AddBookInput input)    {        var newBook = new Book        {            Id = _books.Max(b => b.Id) + 1,            Title = input.Title,            Author = input.Author,            Year = input.Year        };        _books.Add(newBook);        return newBook;    }