GraphQL API com C#: Guia Passo a Passo para Desenvolvedores .NET

Introdução ao GraphQL e C#

GraphQL é uma linguagem de consulta para APIs que permite aos clientes solicitar apenas os dados de que realmente precisam. Ao contrário do REST, onde a estrutura da resposta é fixa, o GraphQL permite formar consultas de forma flexível e obter exatamente o que é necessário. Neste tutorial, vamos abordar como criar uma API GraphQL completa na plataforma C# (.NET) usando a biblioteca Hot Chocolate.

Este material será útil tanto para iniciantes quanto para desenvolvedores experientes que desejam aprender uma abordagem moderna para construir APIs. Passaremos por todas as etapas: desde a configuração do projeto até a implementação de consultas e mutações. Ao final do artigo, você terá um servidor GraphQL funcional, pronto para integração com qualquer cliente.

Instalação e configuração do projeto

Primeiramente, precisamos criar um novo projeto ASP.NET Core. Abra o terminal ou prompt de comando e execute o comando:

dotnet new web -n GraphQLDemocd GraphQLDemo

Agora, adicione o pacote Hot Chocolate — a principal biblioteca para trabalhar com GraphQL no .NET:

dotnet add package HotChocolate.AspNetCore

Após a instalação, abra o arquivo Program.cs e configure os serviços. Aqui está a configuração mínima para executar o GraphQL:

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

var builder = WebApplication.CreateBuilder(args);

// Adiciona os serviços GraphQLbuilder.Services    .AddGraphQLServer()    .AddQueryType<Query>();

var app = builder.Build();

// Conecta o middleware para GraphQLapp.MapGraphQL();

app.Run();

Observe: ainda não criamos a classe Query. Este é nosso tipo raiz, que define as consultas disponíveis. Vamos criá-lo na próxima seção.

Definição do esquema: tipos e resolvers

Criação do modelo de dados

Para começar, vamos definir um modelo de dados simples. Que seja um livro:

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

Criação da classe Query

Agora, vamos criar a classe Query, que retornará os dados. No Hot Chocolate, os resolvers são métodos comuns, que podem ser síncronos ou assíncronos:

public class Query{    private static readonly List<Book> Books = new()    {        new Book { Id = "1", Title = "Guerra e Paz", Author = "Liev Tolstói", Year = 1869 },        new Book { Id = "2", Title = "Crime e Castigo", Author = "Fiódor Dostoiévski", Year = 1866 }    };

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

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

O método GetBooks retorna a lista de todos os livros, e GetBook retorna um livro pelo identificador. O Hot Chocolate converte automaticamente esses métodos em campos do esquema GraphQL.

Configuração de tipos (opcional)

Às vezes, é necessário especificar explicitamente quais campos devem estar disponíveis. Para isso, podem ser usados atributos ou Fluent API. Exemplo com 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; }}

Agora, execute o projeto com o comando dotnet run e acesse no navegador o endereço http://localhost:5000/graphql. Você verá o Banana Cake Pop integrado — um ambiente para testar consultas.

Implementação de mutações (criação, atualização, exclusão)

Mutações no GraphQL são usadas para modificar dados. Vamos criar a classe Mutation e adicionar métodos para trabalhar com livros.