GraphQL API com C#: tutorial passo a passo para desenvolvedores .NET

Introdução ao GraphQL na plataforma .NET

GraphQL é uma linguagem de consulta para APIs que permite aos clientes obter apenas os dados de que realmente precisam. Diferente do REST, onde a estrutura da resposta é rigidamente definida pelo servidor, o GraphQL permite formar consultas de forma flexível. Neste tutorial, criaremos uma API GraphQL completa em C# usando o framework Hot Chocolate — a solução mais popular para .NET.

Percorreremos o caminho desde a instalação até a criação de consultas complexas com mutações e subscrições. O artigo é voltado para desenvolvedores familiarizados com os fundamentos de C# e ASP.NET Core.

1. Configuração do projeto e instalação de dependências

Para começar, criaremos um novo projeto ASP.NET Core. Você pode usar Visual Studio, Rider ou a linha de comando.

dotnet new web -n GraphQLDemocd GraphQLDemo

Agora instalaremos o pacote Hot Chocolate — a ferramenta principal para trabalhar com GraphQL no .NET:

dotnet add package HotChocolate.AspNetCore

Adicionalmente, para trabalhar com consultas através do GraphQL IDE (Banana Cake Pop), instalaremos:

dotnet add package HotChocolate.AspNetCore.Playground

1.1 Configuração básica do Program.cs

Abra o arquivo Program.cs e configure os serviços:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.MapGraphQL();

app.Run();

Observe: registramos Query — este é nosso tipo raiz para leitura de dados. Por enquanto está vazio, mas vamos preenchê-lo.

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

GraphQL trabalha com tipos. Vamos criar um modelo simples Book:

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

Agora definiremos a classe Query, que retornará os dados:

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);}

Execute a aplicação e abra http://localhost:5000/graphql. Você verá o Banana Cake Pop — uma IDE integrada para testar consultas. Tente executar:

{  books {    title    author  }}

Você receberá apenas os campos que solicitou — esta é a força do GraphQL.

3. Mutações para alterar dados

Mutações são o equivalente a POST/PUT/DELETE no REST. Elas permitem alterar dados no servidor. Adicionaremos a capacidade de incluir novos livros.

3.1 Definição do tipo de entrada

Criaremos uma classe para os dados de entrada da mutação:

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

3.2 Implementação da mutação

Adicionaremos a classe 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;    }