GraphQL API com C#: Tutorial prático passo a passo

Introdução: Por que GraphQL e C# são a combinação ideal

O desenvolvimento web moderno exige APIs flexíveis e performáticas. Apesar de sua popularidade, a API REST frequentemente sofre de over-fetching (obtenção de dados desnecessários) e under-fetching (necessidade de várias requisições para obter informações completas). O GraphQL resolve esses problemas, permitindo que o cliente solicite apenas o que precisa em uma única requisição.

Neste tutorial, criaremos uma API GraphQL completa em C# usando a biblioteca Hot Chocolate — a implementação GraphQL mais popular para .NET. Você aprenderá a configurar o servidor, definir o esquema, implementar consultas (queries), mutações (mutations) e assinaturas (subscriptions). Todos os exemplos de código serão práticos e prontos para uso.

Para quem é este material: para desenvolvedores .NET que desejam aprender GraphQL e para aqueles que buscam uma alternativa ao REST. Conhecimentos básicos de C# e ASP.NET Core serão úteis, mas não obrigatórios.

1. Configuração do projeto e instalação do Hot Chocolate

Criação do projeto ASP.NET Core

Vamos começar criando um novo projeto. Abra o terminal ou prompt de comando e execute:

dotnet new web -n GraphQLDemo\ncd GraphQLDemo

Agora, instale o pacote Hot Chocolate:

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

O pacote HotChocolate.AspNetCore adiciona o middleware para processar requisições GraphQL, e o HotChocolate.AspNetCore.Playground fornece uma IDE integrada (GraphQL Playground) para testes.

Configuração do Startup

Edite o arquivo Program.cs (ou Startup.cs para .NET 5 e versões anteriores). Vamos adicionar a configuração básica:

var builder = WebApplication.CreateBuilder(args);\n\n// Adiciona serviços GraphQL\nbuilder.Services\n    .AddGraphQLServer()\n    .AddQueryType<Query>()\n    .AddMutationType<Mutation>(); // adicionaremos depois\n\nvar app = builder.Build();\n\n// Adiciona middleware\napp.UseRouting();\napp.MapGraphQL(); // endpoint /graphql\napp.MapGraphQLPlayground(); // Playground disponível em /playground\n\napp.Run();

Observe: Query e Mutation são classes que criaremos a seguir. Por enquanto, deixaremos apenas o Query.

2. Criação do modelo de dados e primeira consulta (Query)

Modelo Book

Vamos criar um modelo simples de livro. Adicione o arquivo 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}

Classe Query

Agora, crie a classe Query, que conterá os métodos para obter dados. Adicione o arquivo GraphQL/Query.cs:

using GraphQLDemo.Models;\n\nnamespace GraphQLDemo.GraphQL;\n\npublic class Query\n{\n    // Armazenamento temporário de dados (em um projeto real, seria um banco de dados)\n    private static readonly List<Book> Books = new()\n    {\n        new Book { Id = 1, Title = "Guerra e Paz", Author = "Liev Tolstói", Year = 1869, Price = 29.99m },\n        new Book { Id = 2, Title = "Crime e Castigo", Author = "Fiódor Dostoiévski", Year = 1866, Price = 24.99m },\n        new Book { Id = 3, Title = "O Mestre e a Margarida", Author = "Mikhail Bulgákov", Year = 1967, Price = 19.99m }\n    };\n\n    // Consulta: obter todos os livros\n    public IQueryable<Book> GetBooks() => Books.AsQueryable();\n\n    // Consulta: obter livro por ID\n    public Book? GetBookById(int id) => Books.FirstOrDefault(b => b.Id == id);\n}

Os métodos que retornam dados são chamados de resolvers. O Hot Chocolate automaticamente