GraphQL In ASP.NET Core: A Practical Guide

Hey everyone! Today, we're diving into the world of GraphQL and how you can seamlessly integrate it into your ASP.NET Core APIs. If you've been working with REST, you might be curious about what GraphQL brings to the table. Well, get ready, because we're about to explore the power and flexibility it offers.

What is GraphQL?

So, what exactly is GraphQL? In simple terms, it's a query language for your API and a server-side runtime for executing those queries. Unlike REST, where the server dictates the structure of the data, GraphQL empowers the client to request exactly what they need and nothing more. This eliminates over-fetching and under-fetching of data, making your APIs more efficient and your applications faster. Think of it like ordering at a restaurant: with REST, you get a pre-set menu, but with GraphQL, you tell the chef exactly what ingredients you want in your dish.

Why should you care about GraphQL? Well, imagine you're building a mobile app that needs to display a user's profile information. With REST, you might hit an endpoint like /users/{id}, which returns a whole bunch of data, even if you only need the user's name and profile picture. GraphQL lets you specify precisely those fields, reducing the amount of data transferred and improving the app's performance. This is especially crucial on mobile networks where bandwidth is limited. Also, GraphQL is strongly typed, using a schema to define the types of data that can be queried. This brings benefits like introspection, which allows tools to discover the API's capabilities, and validation, which catches errors early in the development process.

Benefits of Using GraphQL

Let's break down the key advantages of using GraphQL in your ASP.NET Core projects:

Efficiency: Clients request only the data they need, reducing bandwidth usage and improving performance. Imagine loading a social media feed; instead of getting all user data, you grab just usernames and profile pics. This is a huge win for mobile apps! GraphQL helps to retrieve only the specific data elements that are required for a client application, thus greatly optimizing data transfer over the network. This is extremely beneficial in scenarios where bandwidth is limited or when dealing with mobile devices.
Flexibility: GraphQL adapts to evolving client requirements without requiring changes to the server. As your application evolves, you can add or remove fields from your queries without affecting the underlying API. It’s like having a LEGO set – you can build whatever you need without changing the entire structure. GraphQL offers great flexibility for developers, allowing them to tailor data requests as needed without modifying the server-side code. This is particularly beneficial when applications evolve or when working with different clients that require different data sets.
Strong Typing: The GraphQL schema defines the types of data available, enabling introspection and validation. This helps you catch errors early and build more robust APIs. Strong typing ensures that data adheres to a predefined structure, facilitating early error detection and promoting code maintainability. It’s like having a blueprint for your data, ensuring everyone is on the same page. GraphQL schemas provide a clear contract between the client and the server, defining the structure and types of data that can be queried.
API Evolution: GraphQL simplifies versioning as changes can be made without impacting existing clients. You can add new fields and deprecate old ones without breaking existing queries. It's like upgrading your car's features without having to buy a new car. GraphQL simplifies API versioning by allowing changes and additions without disrupting existing client applications. You can introduce new features or deprecate older ones while maintaining compatibility with previous versions.

Setting Up GraphQL in ASP.NET Core

Alright, let's get our hands dirty and set up GraphQL in an ASP.NET Core API. We'll use the HotChocolate library, which is a popular and powerful GraphQL implementation for .NET.

1. Create a New ASP.NET Core Web API Project

First, let's create a brand new ASP.NET Core Web API project. Open your terminal and run:

dotnet new webapi -n GraphQLDemo
cd GraphQLDemo

This creates a new project named GraphQLDemo and navigates into the project directory.

2. Install the HotChocolate NuGet Package

Next, we need to install the HotChocolate NuGet package. Run the following command:

dotnet add package HotChocolate.AspNetCore

This adds the necessary GraphQL libraries to your project.

3. Define a GraphQL Type

Let's define a simple GraphQL type. Create a new folder called Models and add a class named Book.cs:

namespace GraphQLDemo.Models
{
    public class Book
    {
        public int Id { get; set; }
        public string Title { get; set; }
        public string Author { get; set; }
    }
}

This is a simple Book class with properties for Id, Title, and Author.

4. Create a Query Type

Now, let's create a query type that will allow us to fetch books. Create a new folder called GraphQL and add a class named Query.cs:

using GraphQLDemo.Models;

namespace GraphQLDemo.GraphQL
{
    public class Query
    {
        public Book GetBook() =>
            new Book
            {
                Id = 1,
                Title = "The Lord of the Rings",
                Author = "J.R.R. Tolkien"
            };
    }
}

This Query class has a GetBook method that returns a hardcoded book. In a real-world scenario, you'd fetch this data from a database.

5. Configure GraphQL in Startup.cs

Now, let's configure GraphQL in your Startup.cs file. First, add the following using statement at the top of the file:

using GraphQLDemo.GraphQL;

Then, in the ConfigureServices method, add the following code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddGraphQLServer()
        .AddQueryType<Query>();
}

This registers the GraphQL server and adds our Query type.

Finally, in the Configure method, add the following code:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

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

This maps the /graphql endpoint to the GraphQL server.

6. Run Your Application and Test the GraphQL Endpoint

Now, run your application by typing dotnet run in the terminal. Open your browser and navigate to https://localhost:{your_port}/graphql. You should see the GraphQL Playground, which is a powerful tool for exploring and testing your GraphQL API.

In the GraphQL Playground, enter the following query:

| Read Also : Osiyani Today Episode: Get The Latest Scoop!

query {
  getBook {
    id
    title
    author
  }
}

Click the play button, and you should see the following result:

{
  "data": {
    "getBook": {
      "id": 1,
      "title": "The Lord of the Rings",
      "author": "J.R.R. Tolkien"
    }
  }
}

Congratulations! You've successfully set up GraphQL in your ASP.NET Core API.

Advanced GraphQL Features

Now that we've got the basics down, let's explore some advanced GraphQL features that can take your APIs to the next level.

Mutations

Mutations are used to modify data on the server. They're like the POST, PUT, and DELETE methods in REST. Let's add a mutation to create a new book.

1. Create a Mutation Type

Create a new class called Mutation.cs in the GraphQL folder:

using GraphQLDemo.Models;

namespace GraphQLDemo.GraphQL
{
    public class Mutation
    {
        public Book CreateBook(string title, string author)
        {
            // In a real-world scenario, you'd save this to a database
            return new Book
            {
                Id = new Random().Next(),
                Title = title,
                Author = author
            };
        }
    }
}

This Mutation class has a CreateBook method that creates a new book with a random ID. Again, in a real-world scenario, you'd save this to a database.

2. Configure the Mutation Type in Startup.cs

In the ConfigureServices method of your Startup.cs file, add the following code to register the Mutation type:

services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>();

3. Test the Mutation

Run your application and open the GraphQL Playground. Enter the following mutation:

mutation {
  createBook(title: "The Hobbit", author: "J.R.R. Tolkien") {
    id
    title
    author
  }
}

Click the play button, and you should see a new book with a random ID.

Subscriptions

Subscriptions enable real-time updates from the server to the client. They're like WebSockets for GraphQL. Let's add a subscription to get notified when a new book is created.

1. Create a Subscription Type

Create a new class called Subscription.cs in the GraphQL folder:

using GraphQLDemo.Models;
using System.Reactive.Subjects;

namespace GraphQLDemo.GraphQL
{
    public class Subscription
    {
        private readonly Subject<Book> _bookStream = new Subject<Book>();

        public Book SubscribeToNewBooks() =>
            _bookStream.AsObservable();

        public void AddNewBook(Book book)
        {
            _bookStream.OnNext(book);
        }
    }
}

This Subscription class uses a Subject to manage the stream of new books. The SubscribeToNewBooks method returns an observable that clients can subscribe to. The AddNewBook method adds a new book to the stream.

2. Modify the Mutation Type to Publish New Books

Modify the CreateBook method in your Mutation.cs file to publish new books to the subscription:

using GraphQLDemo.Models;

namespace GraphQLDemo.GraphQL
{
    public class Mutation
    {
        private readonly Subscription _subscription;

        public Mutation(Subscription subscription)
        {
            _subscription = subscription;
        }

        public Book CreateBook(string title, string author)
        {
            var book = new Book
            {
                Id = new Random().Next(),
                Title = title,
                Author = author
            };

            _subscription.AddNewBook(book);

            return book;
        }
    }
}

Note that we've added a dependency on the Subscription class to the Mutation class's constructor.

3. Configure the Subscription Type in Startup.cs

In the ConfigureServices method of your Startup.cs file, add the following code to register the Subscription type:

services.AddSingleton<Subscription>();

services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .AddSubscriptionType<Subscription>();

Also, register the Subscription class as a singleton service.

4. Test the Subscription

Run your application and open the GraphQL Playground. Enter the following subscription:

subscription {
  subscribeToNewBooks {
    id
    title
    author
  }
}

Click the play button, and the GraphQL Playground will start listening for new books. In another tab, enter the following mutation:

mutation {
  createBook(title: "The Silmarillion", author: "J.R.R. Tolkien") {
    id
    title
    author
  }
}

Click the play button, and you should see the new book appear in the subscription tab.

Conclusion

GraphQL offers a powerful and flexible alternative to REST for building APIs. With its ability to fetch exactly the data you need, strong typing, and support for advanced features like mutations and subscriptions, GraphQL can help you build more efficient and robust applications. In this guide, we've covered the basics of setting up GraphQL in an ASP.NET Core API and explored some advanced features that can take your APIs to the next level. So go ahead, give GraphQL a try, and see how it can improve your development workflow and the performance of your applications. Happy coding, guys!