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

Introducción a GraphQL y C#

GraphQL es un lenguaje de consultas para API que permite a los clientes solicitar únicamente los datos que realmente necesitan. A diferencia de REST, donde la estructura de la respuesta es fija, GraphQL permite formar consultas de manera flexible y obtener exactamente lo que se requiere. En este tutorial, analizaremos cómo crear una API GraphQL completa en la plataforma C# (.NET) utilizando la biblioteca Hot Chocolate.

Este material será útil tanto para principiantes como para desarrolladores experimentados que deseen dominar el enfoque moderno para construir API. Recorreremos todas las etapas: desde la configuración del proyecto hasta la implementación de consultas y mutaciones. Al final del artículo, tendrá un servidor GraphQL funcional, listo para integrarse con cualquier cliente.

Instalación y configuración del proyecto

Lo primero que debemos hacer es crear un nuevo proyecto ASP.NET Core. Abra la terminal o la línea de comandos y ejecute el comando:

dotnet new web -n GraphQLDemocd GraphQLDemo

Ahora agreguemos el paquete Hot Chocolate — esta es la biblioteca principal para trabajar con GraphQL en .NET:

dotnet add package HotChocolate.AspNetCore

Después de la instalación, abra el archivo Program.cs y configure los servicios. Aquí está la configuración mínima para ejecutar GraphQL:

using Microsoft.AspNetCore.Builder;using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Agregamos servicios GraphQLbuilder.Services    .AddGraphQLServer()    .AddQueryType<Query>();

var app = builder.Build();

// Conectamos el middleware para GraphQLapp.MapGraphQL();

app.Run();

Tenga en cuenta: aún no hemos creado la clase Query. Este es nuestro tipo raíz, que define las consultas disponibles. Lo crearemos en la siguiente sección.

Definición del esquema: tipos y resolvers

Creación del modelo de datos

Para empezar, definamos un modelo de datos simple. Que sea un libro:

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

Creación de la clase Query

Ahora creemos la clase Query, que devolverá los datos. En Hot Chocolate, los resolvers son métodos comunes que pueden ser síncronos o asíncronos:

public class Query{    private static readonly List<Book> Books = new()    {        new Book { Id = "1", Title = "Guerra y paz", Author = "León Tolstói", Year = 1869 },        new Book { Id = "2", Title = "Crimen y castigo", Author = "Fiódor Dostoyevski", Year = 1866 }    };

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

    public Book? GetBook(string id) => Books.FirstOrDefault(b => b.Id == id);}

El método GetBooks devuelve la lista de todos los libros, y GetBook devuelve un libro por su identificador. Hot Chocolate convierte automáticamente estos métodos en campos del esquema GraphQL.

Configuración de tipos (opcional)

A veces es necesario indicar explícitamente qué campos deben estar disponibles. Para ello, se pueden usar atributos o Fluent API. Ejemplo con atributos:

public class Book{    [GraphQLName("id")]    public string Id { get; set; }

    [GraphQLNonNullType]    public string Title { get; set; }

    public string Author { get; set; }    public int Year { get; set; }}

Ahora ejecute el proyecto con el comando dotnet run y vaya en el navegador a la dirección http://localhost:5000/graphql. Verá la herramienta integrada Banana Cake Pop, un entorno para probar consultas.

Implementación de mutaciones (creación, actualización, eliminación)

Las mutaciones en GraphQL se utilizan para modificar datos. Creemos la clase Mutation y agreguemos métodos para trabajar con libros.