GraphQL with .NET: A Modern Approach to API Development in .NET

Introduction

Facebook developed GraphQL, a powerful query language for APIs, in 2012 and released it in 2015. It is an alternative to REST and provides a more flexible and efficient approach to working with data. Unlike REST, where clients have to make multiple requests to different endpoints to fetch related data, GraphQL allows clients to request exactly the data they need in a single request.

Key Features of GraphQL:

• Client-Specified Queries: Clients can define the structure of the response, allowing them to retrieve exactly the data they need and nothing more.
• Single Endpoint: All queries and mutations are made to a single endpoint, unlike REST, where each resource may have its own endpoint.
• Real-Time Data: GraphQL supports real-time data updates through subscriptions.
• Strongly Typed: GraphQL schemas define the types of data and the relationships between them, making it easy to understand the structure of the API.

Why Use GraphQL with .NET?

.NET has been traditionally used to build RESTful APIs.

But with the growing popularity of GraphQL, developers have increasingly started integrating GraphQL into .NET-based applications. Some of the main reasons to use GraphQL in .NET are:

• Efficiency: Reduce over-fetching and under-fetching of data, especially in mobile and front-end applications.
• Unified Data Source: GraphQL can be used as a single data layer, unifying multiple data sources (e.g., databases, third-party APIs, microservices).
• Developer Productivity: With its introspective nature and type system, GraphQL can speed up development, debugging, and maintenance.
• Flexibility: Clients can control exactly what data is returned, which results in better performance, especially with mobile clients.

Setting Up a GraphQL API in .NET

In this section, we will go through a step-by-step process of setting up a GraphQL API in a .NET application. We will use HotChocolate, a popular GraphQL library for .NET, to implement the GraphQL API. HotChocolate is a fully-featured, fast, and lightweight GraphQL server for .NET that adheres to the latest GraphQL specifications.

Step 1: Create a New .NET Core Project

First, create a new .NET Core project using Visual Studio or the .NET CLI

dotnet new webapi -n GraphQLExample
cd GraphQLExample 

Step 2: Add Required NuGet Packages

You need to add the HotChocolate GraphQL library to your project to get started with GraphQL

Run the following command to add the necessary NuGet packages:

dotnet add package HotChocolate.AspNetCore
dotnet add package HotChocolate.AspNetCore.Playground 

The core package for integrating GraphQL with ASP.NET Core is HotChocolate.AspNetCore

AspNetCore.Playground is used to provide a UI for querying the API.

Step 3: Create the GraphQL Schema

In GraphQL, schemas define the structure of the API. We will create a simple schema with types and a query.

1. Create a Model (e.g., Book)

Create a class that will represent the data we will query through GraphQL.

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

2. Create a Query Class

Define a class with a query to fetch books.

public class Query
{
    public Book GetBook() => new Book
    {
        Title = "GraphQL in .NET",
        Author = "John Doe",
        Year = 2024
    };
} 

3. Define the GraphQL Schema

We need to register the schema in the Startup.cs file.

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseGraphQLPlayground(); // Enables GraphQL Playground in development mode
        }
        
        app.UseRouting();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapGraphQL(); // Maps the GraphQL endpoint
        });
    }
} 

Step 4: Run the Application

After setting up the GraphQL server, run the application.

dotnet run  

When you configure everything correctly, the GraphQL endpoint becomes available at http://localhost:5000/graphql. You can also access the GraphQL Playground UI (which is available in development mode) at http://localhost:5000/playground, where you can run GraphQL queries interactively.

Step 5: Create a GraphQL Query

Once the API is running, you can open GraphQL Playground and write the following query to fetch the data.

query {
  getBook {
    title
    author
    year
  }
} 

The response will look like this:

{
  "data": {
    "getBook": {
      "title": "GraphQL in .NET",
      "author": "John Doe",
      "year": 2024
    }
  }
} 

Example with Real-Time Data: Subscriptions

GraphQL also supports subscriptions, which allow clients to listen for real-time updates from the server. For example, you could use subscriptions to notify clients when a new book is added to the system.

Step 1: Define a Subscription

You can add a subscription to your schema to listen for new books:

public class Subscription
{
    [Subscribe]
    public Book OnBookAdded([EventMessage] Book book) => book;
}  

Step 2: Update the Startup Configuration

You need to modify the configuration to include subscriptions:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGraphQLServer()
                .AddQueryType<Query>()
                .AddSubscriptionType<Subscription>(); // Register the subscription
    }

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

        app.UseRouting();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapGraphQL(); // Maps GraphQL endpoint
        });
    }
} 

Step 3: Set Up a Client to Listen for Updates

Subscriptions in GraphQL are usually based on WebSocket connections. On the client side, you can use a library like GraphQL.Client or Apollo Client (for JavaScript) to subscribe to events.

For example, a client might subscribe to the OnBookAdded event using a WebSocket connection and update the UI whenever a new book is added.

Best Practices for GraphQL in .NET

1. Use Paging and Filtering: To avoid fetching too much data in a single query, implement paging and filtering for lists. This ensures that the client can request only a subset of data when needed.
2. Security: Implement authentication and authorization for your GraphQL API to ensure that users can only access the data they are allowed to see. Use middleware or directive-based approaches for role-based access control.
3. Caching: Since GraphQL APIs often have complex queries, use caching mechanisms to improve performance. You can cache results or query responses to avoid redundant database calls.
4. Error Handling: Ensure that error messages are handled gracefully and return meaningful responses to the client without exposing sensitive data.

Conclusion

GraphQL provides a modern, efficient approach to building APIs, offering flexible and efficient data retrieval, single endpoint access, and real-time updates. By integrating GraphQL with .NET, developers can take advantage of these benefits while continuing to use the powerful features of the .NET ecosystem. Using libraries like HotChocolate, developers can quickly set up and deploy GraphQL APIs with minimal effort.

By following the steps above, we created a basic GraphQL API with a single query and explored how to handle real-time subscriptions, which can significantly enhance the client-server interaction for dynamic, data-driven applications.