close

Articles Home » Programming Languages » Building a CRUD API with C# and GraphQL

Building a CRUD API with C# and GraphQL

Introduction

What is GraphQL?

GraphQL is a query language for APIs, as well as a runtime for executing those queries using a type system that you define for your data. Unlike other API standards that focus on defining fixed endpoints, GraphQL enables clients to request exactly the data they need, and no more. Developed by Facebook in 2012 and released as an open-source project in 2015, GraphQL provides a more efficient, flexible, and powerful alternative to the traditional REST API.

At its core, GraphQL allows for declarative data fetching where a client can specify exactly what data it needs. Instead of multiple endpoints that return fixed sets of data, a GraphQL server exposes a single endpoint and responds with precisely the data a client asked for.

Advantages of GraphQL over REST

  1. Flexibility for Clients: GraphQL empowers clients to shape the responses according to their needs. This means that applications can fetch the exact data they need, without over-fetching or under-fetching of data. This can be especially beneficial for mobile devices or slow network situations where minimizing the amount and size of the data is crucial.
  2. Single Endpoint: Unlike REST where the design is based around having multiple endpoints for different resources, GraphQL typically exposes a single endpoint. This simplifies the process, reduces the number of requests, and makes versioning more straightforward.
  3. Strongly Typed Schema: With GraphQL, the schema is strongly typed, meaning every data point has a specific type associated with it. This enables introspection, allowing clients to discover capabilities of the schema via the API itself. It also ensures that the data is consistent and adheres to a predetermined structure.
  4. Reduction in Overhead: By allowing clients to request only the data they need, there’s a significant reduction in the amount of data transferred over the network, which can improve application performance, especially on slower connections.
  5. Built-in Documentation: Thanks to its strongly-typed nature and introspection capabilities, GraphQL APIs can be auto-documented. Tools like GraphQL Playground provide interactive documentation for developers, reducing the effort required to keep documentation up-to-date.
  6. Avoid Over-fetching and Under-fetching: One of the primary challenges with REST is the potential to over-fetch or under-fetch data. With GraphQL, the client specifies the required data, ensuring they get exactly what they need without unnecessary additional information or missing any crucial data points.
  7. Easier Versioning: In REST, changes often require a new version of the endpoint, leading to versioning challenges. In GraphQL, new fields can be added to the schema without impacting existing queries, making versioning simpler and more intuitive.
  8. Batching & Caching: Tools like DataLoader can be integrated with GraphQL to batch multiple requests into a single request, and cache requests to optimize performance.

While REST has its own set of advantages and is still widely used, GraphQL offers a more dynamic and flexible approach to designing and consuming APIs. Its focus on allowing clients to define their data requirements makes it particularly well-suited for today’s varied and rapidly evolving application needs.

Understanding the Basics of GraphQL

To fully harness the capabilities of GraphQL when building our API with C#, it’s crucial to grasp some of its foundational concepts. Let’s delve into the basics of GraphQL and understand its main components.

GraphQL Schema

At the heart of any GraphQL API is its schema. The schema defines the types of data you can query and the set of possible operations you can perform. It serves as a contract between the client and the server, describing the shape of the response the client can expect.

In essence, the schema outlines:

  • What can be queried (Queries).
  • How data can be changed (Mutations).
  • The shape and structure of the data objects (Types).

Types

GraphQL is a strongly typed language, and as such, the schema defines specific types that represent the shape of the data you can fetch.

Scalar Types: These are the primitives like Int, Float, String, Boolean, and ID. While these are the default scalar types, you can also define custom scalars for your API if needed.

Object Types: These represent the kind of objects you can fetch from your service and the fields they contain. For instance, consider a Book type:

type Book {
  id: ID!
  title: String!
  author: String!
}Code language: CSS (css)

The ! denotes that the field is non-nullable.

Enum Types: Enums are a special kind of scalar restricted to a particular set of allowed values. They’re useful when an object can be in one of a small set of possible states.

Queries

Queries allow clients to request specific data as per their needs. They represent the “R” in “CRUD” (i.e., read operations). A client specifies what set of data it needs, and the server responds with the matching data.

For example, a simple query to fetch a book by its ID might look like:

query {
  book(id: 1) {
    title
    author
  }
}

Mutations

While queries are all about fetching data, mutations are about modifying data. They represent the “C”, “U”, and “D” in “CRUD” (i.e., create, update, delete operations).

A mutation to add a new book might be structured as:

mutation {
  addBook(title: "New Book", author: "John Doe") {
    id
    title
  }
}Code language: JavaScript (javascript)

Resolvers and their role

Resolvers are functions that handle the process of fetching the data for a particular field in your schema. Every field in a GraphQL schema is backed by a resolver. When a client sends a query or mutation to the server, the GraphQL server invokes the resolver for each field in the received request.

The role of a resolver is twofold:

  1. Data Retrieval: It retrieves the requested data from the source, be it a database, another API, or any other data source.
  2. Data Transformation: Resolvers can also transform the data before sending it back to the client, ensuring it matches the shape defined in the schema.

In essence, resolvers are the bridge between a GraphQL query and the actual backend logic that retrieves or modifies the data.

Setting Up GraphQL in C#

To integrate GraphQL into our C# project, we need to leverage specific libraries that facilitate this integration. One of the most popular libraries for this purpose in the .NET ecosystem is HotChocolate. Alongside, to manage our database interactions, we’ll use Entity Framework Core. Let’s walk through the steps to set everything up.

Installing required NuGet packages

HotChocolate

HotChocolate is a GraphQL server for .NET. It provides all the essential tooling to set up a GraphQL endpoint with ease.

Using .NET CLI:

dotnet add package HotChocolate.AspNetCore
dotnet add package HotChocolate.AspNetCore.PlaygroundCode language: Bash (bash)

Using Visual Studio:

  • Open the “NuGet Package Manager” or “Manage NuGet Packages for Solution”.
  • Search for “HotChocolate.AspNetCore” and install it.
  • Similarly, search for “HotChocolate.AspNetCore.Playground” and install it.

Entity Framework Core

Entity Framework (EF) Core is an ORM (Object-Relational Mapper) that simplifies database operations in .NET applications.

Using .NET CLI (assuming SQL Server as the database, adjust accordingly if using another database provider):

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServerCode language: Bash (bash)

Using Visual Studio:

  • Open the “NuGet Package Manager”.
  • Search for “Microsoft.EntityFrameworkCore” and install it.
  • Similarly, search for “Microsoft.EntityFrameworkCore.SqlServer” and install it.

Integrating GraphQL middleware with ASP.NET Core

Update Startup.cs:After installing the necessary packages, we need to configure our application to use HotChocolate and set up a GraphQL endpoint.

In Startup.cs, add the following using directives:

using HotChocolate;
using HotChocolate.AspNetCore;Code language: C# (cs)

In the ConfigureServices method, register the GraphQL services:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<YourDbContextClass>(options => 
        options.UseSqlServer(Configuration.GetConnectionString("YourConnectionStringName")));

    services.AddGraphQL(sp => 
        SchemaBuilder.New()
        .AddQueryType<YourQueryTypeClass>()
        .AddMutationType<YourMutationTypeClass>()
        .Create());
}Code language: C# (cs)

In the Configure method, integrate the GraphQL middleware and optionally the Playground (a GraphQL IDE) for testing:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ... other middleware ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGraphQL();
    });

    // If you want to use the GraphQL Playground for testing:
    app.UsePlayground();
}Code language: C# (cs)

Define the DbContext and Models:At this point, you’d typically define your Entity Framework DbContext and related models, which would then be used to shape your GraphQL schema. Ensure that your DbContext is properly set up to interact with your database.

GraphQL Types, Queries, and Mutations:We briefly touched upon these in the previous section. You’ll now use C# classes to define these structures in conjunction with HotChocolate. For instance, if you have a Book model, you might create a BookType class to represent it in GraphQL.

With these configurations in place, you’re all set to start defining your GraphQL schema, types, and resolvers using C# and HotChocolate. As you proceed, you’ll find that HotChocolate offers a wide range of features, making it an excellent choice for building sophisticated GraphQL APIs in .NET.

Designing the Data Model

The backbone of any database-driven application lies in its data model, which represents the structured data, relationships, and rules. When working with GraphQL and Entity Framework, it’s pivotal to have a clear understanding of the entities and their relationships, as this directly impacts the GraphQL schema and the queries/mutations you will define.

Entities and their relationships

  1. Book:Represents a book with basic details.
    • Properties: Id, Title, ISBN, PublicationDate, AuthorId, PublisherId
    • Relationships:
      • Many-to-One with Author: A book has one author, but an author can write many books.
      • Many-to-One with Publisher: A book has one publisher, but a publisher can publish many books.
  2. Author:Represents an author who writes books.
    • Properties: Id, Name, DateOfBirth, Biography
    • Relationships:
      • One-to-Many with Book: An author can write many books, but a book is written by one author.
  3. Publisher:Represents a publishing entity.
    • Properties: Id, Name, EstablishedDate, Address
    • Relationships:
      • One-to-Many with Book: A publisher can publish many books, but a book is published by one publisher.

Setting up the Entity Framework context

Define the Entity Models:First, create a Models folder in your project. Inside, define the entities:

// Book.cs
public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string ISBN { get; set; }
    public DateTime PublicationDate { get; set; }
    public Author Author { get; set; }
    public int AuthorId { get; set; }
    public Publisher Publisher { get; set; }
    public int PublisherId { get; set; }
}

// Author.cs
public class Author
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime DateOfBirth { get; set; }
    public string Biography { get; set; }
    public ICollection<Book> Books { get; set; }
}

// Publisher.cs
public class Publisher
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime EstablishedDate { get; set; }
    public string Address { get; set; }
    public ICollection<Book> Books { get; set; }
}Code language: C# (cs)

Setup the DbContext:In the root of your project or inside a Data folder, create a new class for your DbContext:

using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Book> Books { get; set; }
    public DbSet<Author> Authors { get; set; }
    public DbSet<Publisher> Publishers { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Define relationships and any other model configurations here
        modelBuilder.Entity<Book>()
            .HasOne(b => b.Author)
            .WithMany(a => a.Books)
            .HasForeignKey(b => b.AuthorId);

        modelBuilder.Entity<Book>()
            .HasOne(b => b.Publisher)
            .WithMany(p => p.Books)
            .HasForeignKey(b => b.PublisherId);
    }
}Code language: C# (cs)

Configure DbContext in Startup.cs:Remember to register the AppDbContext in the ConfigureServices method:

services.AddDbContext<AppDbContext>(options => 
    options.UseSqlServer(Configuration.GetConnectionString("YourConnectionStringName")));Code language: C# (cs)

With the data model designed and the Entity Framework context set up, we’re now prepared to dive into GraphQL specifics, linking our data model to GraphQL types, queries, and mutations.

Creating the GraphQL Schema

With our data model ready, the next step is to represent these entities in our GraphQL schema. In HotChocolate, we create classes that represent GraphQL object types for each of our data entities.

Defining Types

BookType:This will represent our Book entity in the GraphQL schema.

using HotChocolate.Types;
using YourNamespace.Models;

public class BookType : ObjectType<Book>
{
    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
    {
        descriptor.Description("Represents any book available in the store.");

        descriptor
            .Field(b => b.Id)
            .Description("Represents the unique ID for the book.");

        descriptor
            .Field(b => b.ISBN)
            .Description("Represents the unique ISBN number of the book.");

        descriptor
            .Field(b => b.Author)
            .ResolveWith<Resolvers>(b => b.GetAuthor(default!, default!))
            .UseDbContext<AppDbContext>()
            .Description("This is the author associated with the given book.");

        descriptor
            .Field(b => b.Publisher)
            .ResolveWith<Resolvers>(b => b.GetPublisher(default!, default!))
            .UseDbContext<AppDbContext>()
            .Description("This is the publisher that published the given book.");
    }

    private class Resolvers
    {
        public Author GetAuthor(Book book, [ScopedService] AppDbContext context)
        {
            return context.Authors.FirstOrDefault(a => a.Id == book.AuthorId);
        }

        public Publisher GetPublisher(Book book, [ScopedService] AppDbContext context)
        {
            return context.Publishers.FirstOrDefault(p => p.Id == book.PublisherId);
        }
    }
}Code language: C# (cs)

AuthorType:This will represent our Author entity in the GraphQL schema.

using HotChocolate.Types;

public class AuthorType : ObjectType<Author>
{
    protected override void Configure(IObjectTypeDescriptor<Author> descriptor)
    {
        descriptor.Description("Represents the author of the book.");

        descriptor
            .Field(a => a.Id)
            .Description("Represents the unique ID for the author.");

        descriptor
            .Field(a => a.Books)
            .ResolveWith<Resolvers>(a => a.GetBooks(default!, default!))
            .UseDbContext<AppDbContext>()
            .Description("This is the list of books authored by the given author.");
    }

    private class Resolvers
    {
        public IEnumerable<Book> GetBooks(Author author, [ScopedService] AppDbContext context)
        {
            return context.Books.Where(b => b.AuthorId == author.Id);
        }
    }
}Code language: C# (cs)

PublisherType:Representing our Publisher entity in the GraphQL schema.

using HotChocolate.Types;

public class PublisherType : ObjectType<Publisher>
{
    protected override void Configure(IObjectTypeDescriptor<Publisher> descriptor)
    {
        descriptor.Description("Represents the publisher of the book.");

        descriptor
            .Field(p => p.Id)
            .Description("Represents the unique ID for the publisher.");

        descriptor
            .Field(p => p.Books)
            .ResolveWith<Resolvers>(p => p.GetBooks(default!, default!))
            .UseDbContext<AppDbContext>()
            .Description("This is the list of books published by the given publisher.");
    }

    private class Resolvers
    {
        public IEnumerable<Book> GetBooks(Publisher publisher, [ScopedService] AppDbContext context)
        {
            return context.Books.Where(b => b.PublisherId == publisher.Id);
        }
    }
}Code language: C# (cs)

The above types demonstrate how we can define GraphQL object types in HotChocolate and link them to our data model. The resolvers handle the logic of fetching related entities. The UseDbContext<AppDbContext>() method ensures that we have a scoped database context available for each resolver.

These GraphQL types will play a central role when we define our queries and mutations, shaping the data we can fetch or modify via our GraphQL API.

Defining Queries and Mutations

Once our GraphQL types are set up, the next step is to define how we can interact with the data — both in terms of fetching (queries) and modifying (mutations). Let’s dive into creating these operations for our Book, Author, and Publisher entities.

Fetching data (Queries)

BookQueries:Queries related to fetching book data.

using HotChocolate;
using HotChocolate.Data;
using YourNamespace.Models;
using YourNamespace.Data;

[ExtendObjectType(name: "Query")]
public class BookQueries
{
    [UseDbContext(typeof(AppDbContext))]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Book> GetBooks([ScopedService] AppDbContext context)
    {
        return context.Books;
    }

    public Book GetBook(int id, [ScopedService] AppDbContext context)
    {
        return context.Books.FirstOrDefault(b => b.Id == id);
    }
}Code language: C# (cs)

AuthorQueries:Queries related to fetching author data.

[ExtendObjectType(name: "Query")]
public class AuthorQueries
{
    public Author GetAuthor(int id, [ScopedService] AppDbContext context)
    {
        return context.Authors.FirstOrDefault(a => a.Id == id);
    }

    [UseDbContext(typeof(AppDbContext))]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Author> GetAuthors([ScopedService] AppDbContext context)
    {
        return context.Authors;
    }
}Code language: C# (cs)

PublisherQueries:Queries related to fetching publisher data.

[ExtendObjectType(name: "Query")]
public class PublisherQueries
{
    public Publisher GetPublisher(int id, [ScopedService] AppDbContext context)
    {
        return context.Publishers.FirstOrDefault(p => p.Id == id);
    }

    [UseDbContext(typeof(AppDbContext))]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Publisher> GetPublishers([ScopedService] AppDbContext context)
    {
        return context.Publishers;
    }
}Code language: C# (cs)

Modifying data (Mutations)

BookMutations:Mutations related to modifying book data.

using HotChocolate;
using YourNamespace.Models;
using YourNamespace.Data;

[ExtendObjectType(name: "Mutation")]
public class BookMutations
{
    public Book AddBook(Book book, [ScopedService] AppDbContext context)
    {
        context.Books.Add(book);
        context.SaveChanges();
        return book;
    }

    public Book UpdateBook(int id, Book book, [ScopedService] AppDbContext context)
    {
        var existingBook = context.Books.Find(id);
        if (existingBook == null)
            throw new Exception($"Book with ID {id} not found.");

        existingBook.Title = book.Title;
        // ... other updates ...

        context.SaveChanges();
        return existingBook;
    }
}Code language: C# (cs)

AuthorMutations:Mutations related to modifying author data.

[ExtendObjectType(name: "Mutation")]
public class AuthorMutations
{
    public Author AddAuthor(Author author, [ScopedService] AppDbContext context)
    {
        context.Authors.Add(author);
        context.SaveChanges();
        return author;
    }

    public Author UpdateAuthor(int id, Author author, [ScopedService] AppDbContext context)
    {
        var existingAuthor = context.Authors.Find(id);
        if (existingAuthor == null)
            throw new Exception($"Author with ID {id} not found.");

        existingAuthor.Name = author.Name;
        // ... other updates ...

        context.SaveChanges();
        return existingAuthor;
    }
}Code language: C# (cs)

PublisherMutations:Mutations related to modifying publisher data.

[ExtendObjectType(name: "Mutation")]
public class PublisherMutations
{
    public Publisher AddPublisher(Publisher publisher, [ScopedService] AppDbContext context)
    {
        context.Publishers.Add(publisher);
        context.SaveChanges();
        return publisher;
    }

    public Publisher UpdatePublisher(int id, Publisher publisher, [ScopedService] AppDbContext context)
    {
        var existingPublisher = context.Publishers.Find(id);
        if (existingPublisher == null)
            throw new Exception($"Publisher with ID {id} not found.");

        existingPublisher.Name = publisher.Name;
        // ... other updates ...

        context.SaveChanges();
        return existingPublisher;
    }
}Code language: C# (cs)

Implementing Resolvers

In GraphQL, resolvers are functions that determine how data for a particular field is fetched. They are central to GraphQL’s flexibility, allowing you to specify complex operations per field if needed. While in many cases, the default resolver (fetching a property directly from the parent object) is enough, sometimes we need to customize how a field is resolved, especially when dealing with relationships or aggregated data.

Fetching Data

For our tutorial, let’s delve deeper into the process of fetching data by focusing on retrieving a list of books.

Resolver for getting a list of books:

Resolvers in HotChocolate are typically methods inside our type classes. However, if we need to fetch related data or perform some operations, we can define a custom resolver.

Let’s enhance our BookType from earlier by adding a resolver that fetches the list of books:

using HotChocolate;
using HotChocolate.Types;
using YourNamespace.Data;
using YourNamespace.Models;
using System.Linq;

public class BookType : ObjectType<Book>
{
    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
    {
        descriptor.Description("Represents any book available in the store.");

        // ... other field definitions ...

        descriptor
            .Field(b => b.Author)
            .ResolveWith<Resolvers>(r => r.GetAuthor(default!, default!))
            .UseDbContext<AppDbContext>()
            .Description("This is the author associated with the given book.");
    }

    private class Resolvers
    {
        // This method is a resolver for the 'Author' field in the BookType.
        public Author GetAuthor(Book book, [ScopedService] AppDbContext context)
        {
            return context.Authors.FirstOrDefault(a => a.Id == book.AuthorId);
        }

        // Custom resolver for fetching a list of books.
        public IQueryable<Book> GetBooks([ScopedService] AppDbContext context)
        {
            return context.Books;
        }
    }
}Code language: C# (cs)

Note the use of [ScopedService] attribute on the context parameter. This ensures that we have a scoped database context available in our resolver, which is essential for database operations. The UseDbContext<AppDbContext>() directive is also important as it provides the scoped database context to our resolver.

In this example:

  • We’ve added the GetBooks resolver that fetches all the books from the database.
  • The GetAuthor resolver fetches the author for a particular book, demonstrating how we can fetch related data.

When a client queries for a list of books, HotChocolate will automatically use the GetBooks resolver to fetch the required data.

Creating Data

Resolvers also play a crucial role when it comes to mutations, i.e., changing the data. When a client sends a mutation request, it’s the resolver that handles the operation and determines the data that’s returned.

Resolver for adding a new book:

To allow clients to add a new book, we’ll define a mutation resolver. Mutations are typically separate from our type classes, and we’ll group them based on the operation’s entity.

Let’s see how to create a resolver for adding a new book:

using HotChocolate;
using HotChocolate.Types;
using YourNamespace.Data;
using YourNamespace.Models;
using System.Linq;

public class BookMutations
{
    [ExtendObjectType(name: "Mutation")]
    public class BookMutationType
    {
        // Resolver for adding a new book
        public Book AddBook(
            BookInput input, // Define an input type for our mutation
            [ScopedService] AppDbContext context) // Scoped EF Core DbContext
        {
            var book = new Book
            {
                Title = input.Title,
                ISBN = input.ISBN,
                PublicationDate = input.PublicationDate,
                AuthorId = input.AuthorId,
                PublisherId = input.PublisherId
            };

            context.Books.Add(book);
            context.SaveChanges();

            return book;
        }
    }

    // Define the input type for the 'AddBook' mutation
    public class BookInput
    {
        public string Title { get; set; }
        public string ISBN { get; set; }
        public DateTime PublicationDate { get; set; }
        public int AuthorId { get; set; }
        public int PublisherId { get; set; }
    }
}Code language: C# (cs)

Here’s the breakdown of the code:

  • We have a BookMutationType class that contains our mutation resolvers related to books.
  • The AddBook method is our resolver for adding a new book. This method:
    • Takes in a BookInput object which is a representation of our input data for the mutation.
    • Uses the provided AppDbContext to add the new book to the database and save the changes.
    • Returns the newly added book.
  • The BookInput class is an input type that represents the shape of the data we expect from clients when they want to add a new book.

With this setup, a client can now send a mutation request to add a new book. For instance, the client-side GraphQL mutation might look like:

mutation {
  addBook(input: {
    title: "New GraphQL Book",
    ISBN: "123456789",
    publicationDate: "2023-10-05",
    authorId: 1,
    publisherId: 1
  }) {
    id
    title
  }
}Code language: SQL (Structured Query Language) (sql)

This mutation will use the AddBook resolver to add a new book to the database and return the id and title of the newly added book.

Updating Data

When it comes to updating data in our system through GraphQL, we’ll use mutation resolvers similar to creating data. The difference typically lies in how the resolver handles the provided input—finding the existing data and updating its attributes.

Resolver for updating an existing book’s details:

Let’s see how to create a resolver to update an existing book:

using HotChocolate;
using HotChocolate.Types;
using YourNamespace.Data;
using YourNamespace.Models;
using System.Linq;

[ExtendObjectType(name: "Mutation")]
public class BookUpdateMutations
{
    // Resolver for updating a book's details
    public Book UpdateBook(
        UpdateBookInput input, // Define an input type for our mutation
        [ScopedService] AppDbContext context) // Scoped EF Core DbContext
    {
        var existingBook = context.Books.Find(input.Id);
        
        if (existingBook == null)
            throw new GraphQLException($"Book with ID {input.Id} not found.");

        if (!string.IsNullOrEmpty(input.Title))
            existingBook.Title = input.Title;

        if (!string.IsNullOrEmpty(input.ISBN))
            existingBook.ISBN = input.ISBN;

        if (input.PublicationDate.HasValue)
            existingBook.PublicationDate = input.PublicationDate.Value;

        if (input.AuthorId.HasValue)
            existingBook.AuthorId = input.AuthorId.Value;

        if (input.PublisherId.HasValue)
            existingBook.PublisherId = input.PublisherId.Value;

        context.SaveChanges();

        return existingBook;
    }

    // Define the input type for the 'UpdateBook' mutation
    public class UpdateBookInput
    {
        public int Id { get; set; }
        public string? Title { get; set; }
        public string? ISBN { get; set; }
        public DateTime? PublicationDate { get; set; }
        public int? AuthorId { get; set; }
        public int? PublisherId { get; set; }
    }
}Code language: C# (cs)

Here’s what’s happening in the code:

  • The UpdateBook method is our resolver for updating an existing book’s details. This method:
    • Fetches the existing book from the database using the provided Id from the input.
    • Checks if the book exists; if not, it throws an exception.
    • Updates the book’s attributes based on the provided input.
    • Saves the changes to the database.
    • Returns the updated book.
  • The UpdateBookInput class represents the shape of the data we expect from clients when they want to update a book. The use of nullable fields allows clients to provide only the fields they wish to update.

A client-side GraphQL mutation for updating a book might look like:

mutation {
  updateBook(input: {
    id: 1,
    title: "Updated GraphQL Book",
    ISBN: "987654321"
  }) {
    id
    title
    ISBN
  }
}Code language: JavaScript (javascript)

This mutation will use the UpdateBook resolver to update the title and ISBN of the book with ID 1 and return the updated id, title, and ISBN.

Deleting Data

Deleting data through a GraphQL API involves creating a mutation resolver that interacts with the database to remove the specified entity based on the provided criteria.

Resolver for deleting a book:

Let’s create a resolver to delete a book based on its ID:

using HotChocolate;
using HotChocolate.Types;
using YourNamespace.Data;
using YourNamespace.Models;
using System.Linq;

[ExtendObjectType(name: "Mutation")]
public class BookDeleteMutations
{
    // Resolver for deleting a book
    public bool DeleteBook(
        int id, // We need only the ID to delete the book
        [ScopedService] AppDbContext context) // Scoped EF Core DbContext
    {
        var existingBook = context.Books.Find(id);
        
        if (existingBook == null)
            throw new GraphQLException($"Book with ID {id} not found.");

        context.Books.Remove(existingBook);
        context.SaveChanges();

        return true; // Return true to indicate the operation was successful
    }
}Code language: C# (cs)

Here’s the breakdown:

  • The DeleteBook method is our resolver for deleting a book. This method:
    • Fetches the book to be deleted from the database using the provided id.
    • Checks if the book exists; if not, it throws an exception.
    • Removes the book from the database.
    • Saves the changes to the database.
    • Returns true to indicate the operation was successful.

For the client side, a GraphQL mutation to delete a book might look something like:

mutation {
  deleteBook(id: 1)
}

This mutation will use the DeleteBook resolver to delete the book with ID 1 and return true if the operation was successful.

Deletion is a sensitive operation and should be approached with caution. Always ensure:

  • Proper error handling.
  • Adequate permissions and validations (you don’t want just anyone to delete data).
  • Consider using soft deletes (marking data as deleted without actually removing it) if data retention is important for your use case.

Error Handling in GraphQL

Effective error handling is essential in any API, and GraphQL is no exception. GraphQL APIs can emit a variety of errors, ranging from validation to server issues. These errors are conveyed to the client in the errors field of the response.

Common GraphQL errors and their solutions:

  1. Field Validation Errors:
    • Cause: A request asks for a field that doesn’t exist.
    • Solution: Check for typos or out-of-date schema on the client side.
  2. Argument Validation Errors:
    • Cause: The client might provide an argument that isn’t expected.
    • Solution: Verify the arguments in the request and ensure they align with the schema.
  3. Authentication and Authorization Errors:
    • Cause: A client might try to access data they aren’t authorized to see, or they might not be authenticated.
    • Solution: Ensure proper authentication and authorization mechanisms. Provide clear error messages so clients can act accordingly (e.g., re-authenticate or request access).
  4. Query Depth Exceeding Limit:
    • Cause: To prevent overly complex queries that could lead to performance issues, GraphQL servers might limit query depth.
    • Solution: Restructure the query to reduce its depth or increase the server’s depth limit (with caution).
  5. Database Errors:
    • Cause: Issues related to fetching or writing data to the database.
    • Solution: These errors are usually handled server-side. Ensure the database connection is stable and that queries are structured correctly.

Implementing custom error handling:

With HotChocolate, you can add custom error handling to provide more context or to log errors for debugging.

Custom Error Filter:Create a class that implements IErrorFilter to customize error handling:

using HotChocolate;

public class CustomErrorFilter : IErrorFilter
{
    public IError OnError(IError error)
    {
        // You can inspect the error and decide what to do:
        // Log the error, modify the error message, etc.
        return error.WithMessage($"Custom Error: {error.Message}");
    }
}Code language: C# (cs)

Register the Error Filter:In Startup.cs, register the custom error filter:

services.AddGraphQL(...)
        .AddErrorFilter<CustomErrorFilter>();Code language: C# (cs)

Handle Errors in Resolvers:If you encounter an error in your resolver, you can throw a specific exception. This exception can then be handled by your error filter:

[UseExceptionHandler]
public Book AddBook(BookInput input, [ScopedService] AppDbContext context)
{
    // ... Logic ...

    if (someErrorCondition)
    {
        throw new GraphQLException("A custom error occurred while adding the book.");
    }

    // ... More Logic ...
}Code language: C# (cs)

In the example above, if someErrorCondition is true, a custom error is thrown. This error will be captured by our CustomErrorFilter, and the message will be modified before being sent to the client.

Implementing Authorization and Authentication

Implementing authentication and authorization is essential to secure your GraphQL API. Authentication verifies the identity of a user, while authorization determines what an authenticated user can access.

Integrating JWT with GraphQL:

Setting up JWT Middleware:First, ensure your application is set up to issue and validate JWT tokens, often done with ASP.NET Core’s built-in JWT bearer authentication middleware.

// In Startup.cs - ConfigureServices method

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = Configuration["Jwt:Issuer"],
                ValidAudience = Configuration["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Jwt:Key"]))
            };
        });Code language: C# (cs)

Applying Authentication to GraphQL:Ensure authentication middleware is applied before GraphQL in the request pipeline.

// In Startup.cs - Configure method

app.UseAuthentication();
app.UseAuthorization();Code language: C# (cs)

Protecting specific fields or types with authorization:

With HotChocolate, you can use the [Authorize] attribute to protect specific fields or types.

Protecting a Type:You can protect an entire type by applying the [Authorize] attribute. This ensures that only authenticated users can access this type.

[Authorize]
public class BookType : ObjectType<Book>
{
    // ... Type configuration ...
}Code language: C# (cs)

Protecting a Field:If you want to protect just a specific field, you can apply the [Authorize] attribute to that field.

public class BookType : ObjectType<Book>
{
    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
    {
        descriptor.Field(b => b.Title).Authorize();
        // ... other configurations ...
    }
}Code language: C# (cs)

Role-Based Authorization:You can also implement role-based authorization using the [Authorize] attribute.

// Only users with the "Admin" role can access this field
descriptor.Field(b => b.ISBN).Authorize("Admin");Code language: C# (cs)

Custom Authorization:If you need more fine-grained control, you can implement custom authorization policies in ASP.NET Core and then reference them in your GraphQL types or fields.

services.AddAuthorization(options =>
{
    options.AddPolicy("CustomPolicy", policy => 
        policy.RequireClaim("CustomClaim", "ClaimValue"));
});Code language: C# (cs)

Then, in your GraphQL type:

services.AddAuthorization(options =>
{
    options.AddPolicy("CustomPolicy", policy => 
        policy.RequireClaim("CustomClaim", "ClaimValue"));
});Code language: C# (cs)

When implementing authentication and authorization, always test thoroughly to ensure security requirements are met. Consider edge cases and ensure that unauthorized access is effectively prevented. Make sure that error messages from authentication or authorization failures don’t reveal too much information about your system’s internal workings or configurations.

Optimizing Your GraphQL API

As with any API, performance and scalability concerns are vital in GraphQL. One of the common pitfalls in GraphQL is the N+1 problem, where, for example, retrieving an author for each book in a list of books results in one request for the list and then an additional request for the author of each book.

Luckily, a solution exists in the form of DataLoader. DataLoader is a generic utility that batches and caches requests, vastly improving the performance of our GraphQL API.

Benefits of using DataLoader:

  1. Batching: Multiple requests to retrieve a type are batched into a single request, reducing the total number of database hits.
  2. Caching: Results from the database are cached in memory to prevent redundant requests during the lifecycle of a single GraphQL request.

Batch and cache requests to reduce database hits:

Without DataLoader, if we had a query fetching multiple books and their authors, the execution might result in separate database requests for each author. With DataLoader, all these requests can be batched, and the authors fetched in a single query.

Implementing DataLoader in C#:

Let’s see how we can implement DataLoader in a C# GraphQL setup:

Install Required Packages:If you’re using HotChocolate, you can use its built-in DataLoader support. First, install the required package:

Install-Package HotChocolate.DataLoaderCode language: C# (cs)

Create a DataLoader:For our example, let’s create an AuthorDataLoader that fetches authors by their IDs.

public class AuthorDataLoader : BatchDataLoader<int, Author>
{
    private readonly AppDbContext _dbContext;

    public AuthorDataLoader(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    protected override async Task<IReadOnlyDictionary<int, Author>> LoadBatchAsync(
        IReadOnlyList<int> keys, 
        CancellationToken cancellationToken)
    {
        return await _dbContext.Authors
            .Where(a => keys.Contains(a.Id))
            .ToDictionaryAsync(t => t.Id, cancellationToken);
    }
}Code language: C# (cs)

Use DataLoader in Resolvers:Now, when resolving fields, use the DataLoader to fetch data:

public class BookType : ObjectType<Book>
{
    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
    {
        descriptor.Field(b => b.Author)
            .ResolveWith<Resolvers>(r => r.GetAuthor(default!, default!));
    }

    private class Resolvers
    {
        public async Task<Author> GetAuthor(Book book, AuthorDataLoader authorLoader)
        {
            return await authorLoader.LoadAsync(book.AuthorId);
        }
    }
}Code language: C# (cs)

In the example above, when multiple books are fetched, and the author for each book needs to be retrieved, DataLoader will ensure that authors are fetched in a single batch, dramatically reducing the number of database hits.

Using DataLoader can greatly enhance the efficiency and performance of your GraphQL API, especially when dealing with complex queries that fetch related data. By batching and caching requests, DataLoader ensures that your API remains scalable and responsive even under heavy loads.

Testing the CRUD Operations

Once you’ve set up your GraphQL API, it’s essential to test the CRUD operations to ensure everything works as expected. Tools like GraphQL Playground and Postman make this process straightforward and intuitive.

Using GraphQL Playground or Postman:

  1. GraphQL Playground: This is an interactive, in-browser GraphQL IDE. If you’re using HotChocolate, GraphQL Playground comes integrated, and you can access it by navigating to /graphql in your browser after starting your server.
  2. Postman: Postman introduced support for GraphQL, allowing you to test GraphQL APIs just like any other API. To use Postman, set the HTTP verb to POST and set the body type to GraphQL. Provide the GraphQL endpoint URL, and you’re set to test your queries and mutations.

Sample queries and mutations for testing:

Fetch all books:

query {
  getBooks {
    id
    title
    author {
      name
    }
  }
}

Fetch a single book:

query {
  getBook(id: 1) {
    title
    ISBN
    author {
      name
    }
  }
}

Add a new book:

mutation {
  addBook(input: {
    title: "New Book",
    ISBN: "123-456",
    publicationDate: "2023-10-05",
    authorId: 1,
    publisherId: 2
  }) {
    id
    title
  }
}Code language: JavaScript (javascript)

Update a book:

mutation {
  updateBook(input: {
    id: 1,
    title: "Updated Book Title"
  }) {
    id
    title
  }
}Code language: JavaScript (javascript)

Delete a book:

mutation {
  deleteBook(id: 1)
}

You can run these queries and mutations in either GraphQL Playground or Postman to test the operations of your GraphQL API. Ensure to check the responses for correctness and inspect any errors returned. It’s also wise to look into your database directly to verify that the expected changes (especially for mutations) took place.

Best Practices

Ensuring best practices in your GraphQL API can lead to better performance, maintainability, and extensibility. Let’s delve into some important best practices to consider.

Schema Design Recommendations:

  1. Descriptive Naming: Name your types and fields descriptively. Avoid jargon that clients of the API might not understand.
  2. Use Enums and Scalars: For fields that have a specific set of possible values, consider using Enums. Similarly, use custom scalars for specific data types not covered by GraphQL’s default scalars (like Date or DateTime).
  3. Avoid Null Where Possible: While GraphQL supports nullable types, it’s often better to avoid them unless there’s a compelling reason. This ensures clients always receive meaningful data.
  4. Limit Deep Nesting: While GraphQL allows clients to request deeply nested data, consider limiting the depth to prevent overly complex queries.
  5. Use Input Types for Mutations: Instead of having many arguments for mutations, group them into an input type for clarity.

Versioning in GraphQL:

  1. Avoid Versioning if Possible: One of GraphQL’s strengths is its ability to evolve without versioning. Adding fields is non-breaking. Removing or changing fields can be managed by marking them as deprecated.
  2. Schema Extensions: If you must introduce breaking changes, consider extending the schema. For example, introduce new types or fields and deprecate old ones.
  3. Clear Deprecation Messages: When deprecating fields or types, provide clear and meaningful deprecation messages.

Handling N+1 Problem:

  1. Use DataLoader: As covered earlier, DataLoader is an invaluable tool in resolving the N+1 problem by batching and caching requests.
  2. Opt for Batched Endpoints: If integrating with other services, consider batched endpoints that retrieve multiple items in one go.
  3. Limit Field Complexity: It’s good to allow clients the flexibility to request the data they need. However, it might be wise to implement query complexity analysis to prevent overly complicated queries.

GraphQL’s flexibility can be a double-edged sword, leading to potential pitfalls like performance bottlenecks if not managed correctly. Leveraging best practices, utilizing tools like DataLoader, and regularly testing your API are all vital steps in ensuring your GraphQL API remains performant, secure, and scalable.

Related posts: