GraphQL + HotChocolate in .NET —  The Next Evolution of REST

Posted by:

Rob Hutton

|

On:

|

, , , , , , , , , , , ,
, , , , , , ,

REST has been the de facto standard for APIs for years, but as applications grow, it often leads to issues like over-fetching, under-fetching, and rigid endpoint structures. Enter GraphQL — a powerful query language that gives clients the flexibility to request exactly the data they need. This article explores the benefits of GraphQL, how it adheres to SOLID principles and Clean Architecture, and walks through a real-world business case using HotChocolate in .NET.

Benefits of GraphQL Over REST

Data Fetching

With GraphQL, clients request only the fields they need, eliminating over-fetching.

In this example, we are fetching a list of user names along with their associated post titles. This scenario becomes particularly relevant when there are thousands of user records, as the efficiency of data retrieval can significantly impact performance and user experience.

REST
Clients receive fixed data structures from predefined endpoints. Even if we only need the user name, it will always return the entire structure. This inefficiency is magnified when dealing with large datasets or complex entities.

// Fetching Users
GET /api/users

// Response
[
  { "id": 1, "name": "John Doe" },
  { "id": 2, "name": "Jane Smith" }
]

// Fetch Posts for each User
// Separate call for each User
GET /api/users/1/posts

// Response
[
  { "id": 1, "title": "GraphQL is Awesome", "content": "..." },
  { "id": 2, "title": "Understanding REST", "content": "..." }
]

GraphQL
The true super power of GraphQL is that clients can specify exactly what data they need in a single request.

// Fetching Users and Posts
query {
  users {
    name
    posts {
      title
    }
  }
}

// Response
{
  "data": {
    "users": [
      {
        "name": "John Doe",
        "posts": [
          { "title": "GraphQL is Awesome" },
          { "title": "Understanding REST" }
        ]
      },
      {
        "name": "Jane Smith",
        "posts": [
          { "title": "Getting Started with GraphQL" },
          { "title": "REST vs GraphQL" }
        ]
      }
    ]
  }
}

Over-fetching / Under-fetching

Over-fetching occurs when more data is retrieved than necessary, while under-fetching happens when additional requests are required to get related data.

REST
Over-fetching can occur since fixed endpoints return fixed data.

// REST endpoint returns a fixed structure with more data than needed.
// Even if the client only needs the name, it receives all fields.
GET /users/1

GraphQL
Eliminates over-fetching by allowing precise queries.

// With GraphQL, the client requests only the needed fields.
query {
  user(id: 1) {
    name
  }
}

Multiple Resources

With GraphQL, you can get everything you need with one request instead of multiple requests, reducing network overhead and improving performance.

REST
Requires multiple requests for related resources. Multiple API calls increase latency.

// Request 1: Get User Details
GET /users/1

// Response 1
{
  "id": 1,
  "name": "John Doe"
}

// Request 2: Get User's Orders
GET /api/users/1/orders

// Response 2
[
  { "id": 101, "total": 29.99 },
  { "id": 102, "total": 49.99 }
]

GraphQL
Can retrieve related data in a single request. This reduces network overhead by fetching all related data in a single request.

// Retrieves users and orders in a single query
query {
  user(id: 1) {
    name
    orders {
      id
      total
    }
  }
}

// Response
{
  "data": {
    "user": {
      "name": "John Doe",
      "orders": [
        { "id": 101, "total": 29.99 },
        { "id": 102, "total": 49.99 }
      ]
    }
  }
}

Versioning

APIs evolve over time, and maintaining backward compatibility is crucial.

REST
When introducing breaking changes, REST APIs often require new versions. In addition, clients must update to the new version manually.

// Version 1 (/v1/users/1)
GET /api/v1/users/1

// Response (v1)
{
  "id": 1,
  "name": "John Doe"
}

// Version 2 (/v2/users/1)
GET /api/v2/users/1

// Response (v2)
{
  "id": 1,
  "firstName": "John",
  "lastName": "Doe"
}

GraphQL
Instead of new versions, GraphQL allows schema evolution by deprecating fields while keeping backward compatibility.

// Before deprecation
type User {
  id: ID!
  name: String!
  email: String!
}

// With deprecation
type User {
  id: ID!
  name: String @deprecated(reason: "Use firstName and lastName instead")
  firstName: String
  lastName: String
  email: String!
}

Performance

Efficient API performance is crucial for scalability and user experience.

REST
May require multiple API calls, increasing network load. In addition, each request adds network latency.

// Fetch Orders
GET /api/users/1/orders

// Response
[
  {
    "id": 101,
    "date": "2025-02-01",
    "total": 250.00,
    "status": "Shipped",
    "items": [
      {
        "productId": 501,
        "productName": "Wireless Mouse",
        "quantity": 2,
        "price": 25.00
      },
      {
        "productId": 502,
        "productName": "Mechanical Keyboard",
        "quantity": 1,
        "price": 100.00
      }
    ]
  },
  {
    "id": 102,
    "date": "2025-02-10",
    "total": 150.00,
    "status": "Pending",
    "items": [
      {
        "productId": 503,
        "productName": "Gaming Headset",
        "quantity": 1,
        "price": 150.00
      }
    ]
  }
]

// Fetch Payments
GET /api/users/1/payments

// Response
[
  {
    "id": 201,
    "orderId": 101,
    "amount": 250.00,
    "paymentMethod": "Credit Card",
    "date": "2025-02-01",
    "status": "Completed"
  },
  {
    "id": 202,
    "orderId": 102,
    "amount": 150.00,
    "paymentMethod": "PayPal",
    "date": "2025-02-10",
    "status": "Pending"
  }
]

GraphQL
Can be optimized via batched requests and resolvers. Fetches multiple resources in one request, reducing load.

  • Batched Requests: Instead of making multiple individual requests to the server for different pieces of data, batched requests allow you to send a single request that contains multiple queries or mutations.
  • Resolvers: Resolvers are functions that handle fetching the data for a particular field in a GraphQL query. By optimizing resolvers, you can make them more efficient, such as by caching results or using techniques like “lazy loading” to fetch only the necessary data when needed.
// Fetch User, Orders and Payments
query {
  user(id: 1) {
    orders { id total }
    payments { id amount }
  }
}

// Response
{
  "data": {
    "user": {
      "orders": [
        {
          "id": 101,
          "total": 250.00
        },
        {
          "id": 102,
          "total": 150.00
        }
      ],
      "payments": [
        {
          "id": 201,
          "amount": 250.00
        },
        {
          "id": 202,
          "amount": 150.00
        }
      ]
    }
  }
}

Error Handling

Handling errors consistently is essential for debugging and reliability.

REST
Uses HTTP status codes for error handling. Errors are inconsistent across endpoints.

// Fetch Invalid User
GET /api/users/999

// Error Response
{
  "error": "User not found",
  "status": 404
}

GraphQL
Errors are standardized within the response payload resulting in a consistent, structured error response.

// Fetch Invalid User
query {
  user(id: 999) {
    name
  }
}

// Error Response
{
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Caching

Efficient caching improves API performance.

REST
In REST APIs, caching can be achieved using HTTP headers and methods. When a client requests a resource, the server can indicate whether the response can be cached and for how long.

// Fetch Product Details
GET /api/products/1

// Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=3600
{
  "id": 1,
  "name": "Laptop",
  "price": 1200,
  "description": "High-performance laptop."
}
  • The Cache-Control header indicates that this response can be cached by browsers and CDNs for up to 3600 seconds (1 hour).
  • When subsequent requests for the same product are made within this time, the client can use the cached response instead of hitting the server, resulting in faster response times and reduced server load.

GraphQL
In GraphQL, caching strategies can be more complex due to the flexibility of queries. Libraries like Apollo Client provide built-in support for caching.

// Fetch Product Details
query {
  product(id: 1) {
    id
    name
    price
    description
  }
}

// Apollo Client Setup
import { ApolloClient, InMemoryCache } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://your-graphql-endpoint.com/graphql',
  cache: new InMemoryCache(), // Enables in-memory caching
});

// Fetching Data with Caching
client.query({
  query: gql`
    query {
      product(id: 1) {
        id
        name
        price
        description
      }
    }
  `
}).then(response => {
  console.log(response.data.product);
});
  • The InMemoryCache provided by Apollo Client caches the response of the query. If the same query is executed again, Apollo will return the cached data instead of making a network request, improving performance.
  • You can also use advanced caching strategies, such as cache invalidation or merging with existing cache data, giving you fine-tuned control over how your data is cached.

How GraphQL Supports SOLID and Clean Architecture

  • Single Responsibility Principle (SRP): GraphQL resolvers separate concerns by handling only their specific queries.
  • Open/Closed Principle (OCP): New fields can be added without modifying existing code.
  • Liskov Substitution Principle (LSP): GraphQL interfaces allow flexible yet type-safe data structures.
  • Interface Segregation Principle (ISP): Clients request only relevant data instead of dealing with large responses.
  • Dependency Inversion Principle (DIP): Using dependency injection, GraphQL services stay loosely coupled and testable.

Practical Example — Implementing GraphQL to Build a Developer Job Board

Imagine we are developing a job board API where developers can:

  • Browse job listings with specific fields (title, company, location, salary, skills required, etc.).
  • Apply filters (e.g., remote-only, salary range, required skills).
  • Submit applications.

A traditional REST API would require:

  • /jobs for all listings
  • /jobs/{id} for a specific job
  • /companies/{id}/jobs for a company’s jobs
  • Multiple requests to fetch additional details

With GraphQL, we can fetch everything in one request using a single endpoint.

1️⃣ Install HotChocolate in a .NET 8 Web API

Hot Chocolate is a .NET GraphQL server that enables the creation of robust GraphQL APIs with features like schema-first development, powerful data fetching capabilities, and built-in support for GraphQL subscriptions.

dotnet add package HotChocolate.AspNetCore
dotnet add package HotChocolate.Data.EntityFramework

2️⃣ Define the Job Entity

This class defines a Job entity with properties for storing job-related information, including an identifier, title, company name, location, salary, and a list of required skills.

public class Job {
    public int Id { get; set; }
    public string Title { get; set; } = string.Empty;
    public string Company { get; set; } = string.Empty;
    public string Location { get; set; } = string.Empty;
    public decimal Salary { get; set; }
    public List<string> SkillsRequired { get; set; } = new();
}

3️⃣ Create the Database Context

This class, AppDbContext, extends DbContext from Entity Framework Core to define a database context for managing Job entities, allowing for database operations like querying and saving jobs through the Jobs property.

using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext {
    public DbSet<Job> Jobs { get; set; }
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) {}
}

4️⃣ Define the Query Type for Fetching Jobs

This Query class defines a GraphQL query method GetJobs that retrieves a list of Job entities from the database using an AppDbContext, leveraging Hot Chocolate’s data handling features for efficient data fetching.

using HotChocolate;
using HotChocolate.Data;

public class Query {
    [UseDbContext(typeof(AppDbContext))]
    public IQueryable<Job> GetJobs([ScopedService] AppDbContext context) {
        return context.Jobs;
    }
}

5️⃣ Add Filtering and Sorting

These classes, JobFilterType and JobSortType, define input types for filtering and sorting Job entities in a GraphQL API, enabling users to specify criteria for retrieving and organizing job listings.

public class JobFilterType : FilterInputType<Job> {}
public class JobSortType : SortInputType<Job> {}

6️⃣ Define Mutation for Adding Jobs

This Mutation class includes an AddJob method that asynchronously creates a new Job entity with the specified details, adds it to the database context, and saves the changes, returning the newly created job.

public class Mutation {
    public async Task<Job> AddJob(string title, string company, string location, decimal salary,
                                  List<string> skills, [ScopedService] AppDbContext context) {
        var job = new Job { Title = title, Company = company, Location = location,
                            Salary = salary, SkillsRequired = skills };
        context.Jobs.Add(job);
        await context.SaveChangesAsync();
        return job;
    }
}

7️⃣ Configure GraphQL in Program.cs

This code snippet sets up a web application using ASP.NET, creating a database context factory for an in-memory database named “JobBoardDb,” configures a GraphQL server with query and mutation types, and enables filtering and sorting capabilities, before mapping the GraphQL endpoint and running the application.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPooledDbContextFactory<AppDbContext>(options =>
    options.UseInMemoryDatabase("JobBoardDb"));

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .AddFiltering()
    .AddSorting();

var app = builder.Build();
app.MapGraphQL();
app.Run();

8️⃣ Testing with GraphQL Playground

After running the project, visit http://localhost:5000/graphql and test your queries. The GraphQL Playground provides an interactive interface where you can:

  • Explore your schema: The left sidebar will show all available queries and mutations, along with their descriptions.
  • Test your API: You can write and execute queries directly from the interface.

Fetch Jobs

// Fetch all jobs with the location set to "Remote" and sorted by salary in descending order
query {
  jobs(where: { location: { eq: "Remote" }}, order: { salary: DESC }) {
    title
    company
    salary
  }
}

// Response
{
  "data": {
    "jobs": [
      {
        "title": "Senior Software Engineer",
        "company": "Tech Innovators Inc.",
        "salary": 120000.00
      },
      {
        "title": "Product Manager",
        "company": "Remote Solutions LLC",
        "salary": 95000.00
      },
      {
        "title": "UX Designer",
        "company": "Creative Minds Co.",
        "salary": 80000.00
      }
    ]
  }
}

Add Job

// Adds a new job and returns its ID, title, and company
mutation {
  addJob(title: "Senior .NET Developer", company: "Tech Corp",
         location: "Remote", salary: 120000, skills: ["C#", "GraphQL"]) {
    id
    title
    company
  }
}

// Response
{
  "data": {
    "addJob": {
      "id": 1,
      "title": "Senior .NET Developer",
      "company": "Tech Corp"
    }
  }
}

GraphQL is a game-changer for modern APIs. It reduces data over-fetching, improves efficiency, and simplifies API management. With HotChocolate in .NET, we can build scalable, maintainable, and future-proof APIs aligned with SOLID principles and Clean Architecture. As businesses demand more flexibility and efficiency, GraphQL is the next evolution of REST.

Posted by

Rob Hutton

in

, , , , , , , , , , , ,