Deep Thought

GraphQL

5 min read

What is GraphQL?

  • Yet another communication standard
  • Mainly for client ⇔ server
  • GraphQL is typically served over HTTP
    • Contrary to REST we use a single endpoint
  • GraphQL services typically respond using JSON (yet not required by the spec)

Data model

With GraphQL you think of data as a graph of nodes.

flowchart LR
Reward --> ID
Reward --> Title
Reward --> Description
Reward --> Savings
Savings --> S0["Saving[0]"]
Savings --> S1["Saving[1]"]
S0 --> A0[Amount]
S1 --> A1[Amount]

Query language

GraphQL has its own language to query data

{
  rewards {
    title
  }
}
{
  rewards(id: 1) {
    title,
    savings {
      amount
    }
  }
}

Why?

  • GraphQL gives power to the client.
  • The client can specify what they want exactly for a specific use-case.
    • The server needs to be implemented in a way that supports the queries.
  • This leads to very targeted queries fetching only the information that is needed.

Add GraphQL to an ASP.NET Core Web API

Using HotChocolate1

NuGet:

Install-Package HotChocolate.AspNetCore
Install-Package HotChocolate.Data
Install-Package GraphQL.Server.Transports.AspNetCore

Add a query

public class Query  
{  
    public IQueryable<Reward> GetRewards =>  
		new List<Reward>().AsQueryable();    
}

The methods can return any data. We just return an empty list here to get started.

Register with dependency injection

// Program.cs
 
// Type Query points to Query class (previous slide)
builder.Services.AddGraphQLServer().AddQueryType<Query>()
// ...
app.MapGraphQL(path: "/graphql");

Run and verify

Run application and go to route /graphql in the browser.

Create a new document and try out the following query.

query MyQuery {
  getRewards {
    title
  }
}

Should yield result:

{
  "data": {
    "getRewards": []
  }
}

Add connection to database

public class Query  
{  
    [UseProjection]  
    [UseFiltering]  
    [UseSorting]  
    public IQueryable<Reward> GetRewards(
	    [Service] RewardDbContext context) =>  
	        context.Rewards;  
}
// Program.cs
builder.Services.AddGraphQLServer().AddQueryType<Query>()
  .AddProjections().AddFiltering().AddSorting();

Verify again

query GetRewards {
  rewards {
    title
  }
}

returns

{
  "data": {
    "rewards": [
      {
        "title": "X-Jam"
      }
    ]
  }
}

Get element by ID

public class Query  
{    
  [UseFirstOrDefault]  
  [UseProjection]  
  public IQueryable<Reward?> GetReward(
    [Service] RewardDbContext context, 
    int id) =>  
      context.Rewards.Where(r => r.Id == id); 
}
query GetReward {
  reward(id: 1) {
    title
  }
}
{
  "data": {
    "reward": {
      "title": "X-Jam"
    }
  }
}

Add GraphQL to a Blazor WASM Client

Using StrawberryShake2

# in root folder of solution
dotnet new tool-manifest
dotnet tool install StrawberryShake.Tools
 
# in Blazor Client project
Install-Package StrawberryShake.Blazor

Generate client

# server needs to run for this command
# run command in root folder of solution
# use whatever url your server is serving from
dotnet graphql init https://localhost:7232/graphql/ `
-n RewardClient ` # give your generated client a name
-p SavingsPlanner/Client # point to the client project

Customize namespace

// .graphqlrc.json
{  
  "schema": "schema.graphql",  
  "documents": "**/*.graphql",  
  "extensions": {  
    "strawberryShake": {  
      "name": "RewardClient",  
      "namespace": "SavingsPlanner.Client.GraphQL",  
      "url": "https://localhost:7232/graphql/",  
      //...
    }  
  }  
}

Write query definition

# GetRewards.graphql
query GetRewards {  
  rewards {  
    title,  
    description,  
    targetAmount,  
    id  
  }  
}

Build project

dotnet build

Register client with dependency injection

// Program.cs
builder.Services  
    .AddRewardClient()  
    .ConfigureHttpClient(client => 
      client.BaseAddress = new Uri(
        builder.HostEnvironment.BaseAddress + "graphql"));

Query data

@inject RewardClient RewardClient
// ...
await RewardClient.GetRewards.ExecuteAsync();

Mutations

GraphQL Mutations let you modify data.

mutation MyMutation {
  addReward(reward: {
    title: "Apple",
    description: "fruit",
    targetAmount: 1337,
    savingStart: "2023-03-01T00:00:00.000+01:00",
    savingEnd: "2023-04-01T00:00:00.000+01:00",
  }) {
    title,
    id
  }
}

You send the data and have control of what you get back.

Server Implementation

public class Mutation  
{  
    public async Task<RewardListItemDto> AddReward(
      [Service] IRepository<Reward> rewardRepository, 
      AddRewardDto reward)  
    {  
        return await rewardRepository
          .AddAsync<AddRewardDto, RewardListItemDto>(reward);  
    }  
}

It is recommended to create specific types for adding items (e.g. without ID property).

Registration

//Program.cs
builder.Services  
    .AddGraphQLServer()
    // ... your queries
    .AddMutationType<Mutation>();

Update Client

# run from Client directory
# server needs to run
# correct server address needs to be specified in .graphqlrc
dotnet graphql update

Add Definition for Mutation

# AddReward.graphql
mutation AddReward($rewardInput: AddRewardDtoInput!) {  
    addReward(reward: $rewardInput) {
        id  
    }  
}

Build again

dotnet build

Use client to modify data

// NewReward.razor
@inject RewardClient RewardClient
// ...
await RewardClient.AddReward.ExecuteAsync(
  new AddRewardDtoInput()  
  {  
    Title = _title,  
    TargetAmount = _targetAmount,  
    SavingStart = _startDate.Value,  
    SavingEnd = _endDate.Value,  
    Description = _description  
  });

Subscriptions

GraphQL offers an easy way to subscribe to events.
The Server can notify the client of changes via a websocket connection.

sequenceDiagram
	Client->>+Server: Subscribe()
	Note right of Server: Subscription is initiated via HTTP
	Server-->>-Client: ack
	Server->>Client: Update()
	Server->>Client: Update()
	Note right of Server: Updates are sent via WebSocket

Server Implementation

public class Subscription  
{  
  [Subscribe]  
  public RewardListItemDto RewardAdded(
    [EventMessage] RewardListItemDto reward) 
    => reward;  
}

Send subscription message in Mutation

public async Task<RewardListItemDto> AddReward(  
    [Service] IRepository<Reward> rewardRepository,   
    [Service] ITopicEventSender sender,  
    AddRewardDto reward)    
{    
    var addedReward = await rewardRepository  
        .AddAsync<AddRewardDto, RewardListItemDto>(reward);  
    await sender.SendAsync(
      nameof(Subscription.RewardAdded), addedReward);  
    return addedReward;  
}

Registration

// Program.cs
builder.Services  
  .AddGraphQLServer()  
  // ... queries and mutations
  .AddInMemorySubscriptions()
  .AddSubscriptionType<Subscription>();
 
// ...
 
app.UseRouting();
app.UseWebSockets(); // add this line below UseRouting

Test subscriptions

subscription MySubscription {
  rewardAdded {
    id,
    title
  }
}

Client implementation

# run from Client directory
# server needs to run
# correct server address needs to be specified in .graphqlrc
dotnet graphql update
 
# Add NuGet Package
Install-Package StrawberryShake.Transport.WebSockets

Add subscription definition

# SubscribeRewardAdded.graphql
subscription SubscribeRewardAdded {  
    rewardAdded {  
        id,  
        title,  
        description,  
        targetAmount,  
    }  
}

Build project to regenerate client afterwards.

Configuration

// Program.cs
var graphQlUri = new Uri(
  builder.HostEnvironment.BaseAddress + "graphql");  
var graphQlWebSocketUri = new UriBuilder(graphQlUri)  
{  
    Scheme = Uri.UriSchemeWss  
}.Uri;
 
builder.Services.AddRewardClient()  
  .ConfigureHttpClient(client => 
    client.BaseAddress = graphQlUri)  
  .ConfigureWebSocketClient(client => 
    client.Uri = graphQlWebSocketUri);

Use subscription in client

// Rewards.razor
@implements IDisposable
// ...
private IDisposable? rewardAddedSubscription;  
  
protected override async Task OnInitializedAsync()  
{  
  await LoadDataAsync();  
  rewardAddedSubscription = RewardClient  
    .SubscribeRewardAdded  
    .Watch()  
      .Subscribe(message =>  
      {  
        var dto = new RewardListItemDto(
          message.Data.RewardAdded.Id,  
          message.Data.RewardAdded.Title,  
          message.Data.RewardAdded.TargetAmount,  
          message.Data.RewardAdded.Description);  
	    rewards.Add(dto);  
		StateHasChanged();  
	  });  
}
 
public void Dispose()  
{  
    bookAddedSubscription?.Dispose();  
}

Footnotes

  1. Get started with GraphQL in .NET Core ↩

  2. Get started with Strawberry Shake and Blazor ↩

Graph View

Backlinks