No more REST! Long live GraphQL API’s — With C#

Photo by Alina Grubnyak on Unsplash

REST has brought us into a better position since the days of sharing XML contracts through SOAP. It is a good standard and brought us a long way, but what it makes easy to understand and consume can also be a problem.

Resource focused

  • GET /profile
  • GET /orders?customerId={customerId}
  • GET /product/1

Although it’s a nice standard, single resource retrieval’s can be expensive.

The e-commerce order summary example:

In a microservices architecture, a reasonable service split can look like this:

Example diagram with a browser making multiple calls to load a page

GET /profile

GET /order/{customerId}

GET /product/{productId}

Breaking down those calls, there is one call to fetch the customer profile, another one to fetch the orders, and N calls to get each product.

The N calls is a problem, that can easily be 10, 20, 30 REST requests going from the customer browser. That takes time and might consume a lot of their data plan.

The N calls can be fixed, if the products service offered a “get products batch”, where the client passes all the product ids it wants, but then we add complexity to the client-side code, having to compile the dictionary list of products it needs to fetch and mapping it back.

Another downside of this REST approach is the client might be fetching data it doesn’t need, like on my example description is an extra field we might not need on the screen.

Order summary — GraphQL

GraphQL playground — Order summary query

Diagram with the user browser only connecting to Graph Service


  • Only one HTTP call between the browser and the server.
  • Client-side code is having an easy time — It does not need to keep mapping multiple services calls.
  • Flexible queries, the consumers can build the queries to return exactly what they need, nothing more.

There would be internal calls between the Graph service and the previous existing microservices, but I will keep it simple for the coding examples, so the Graph service will do all the work without speaking to other services.

I will cover how the Graph Service would delegate the calls in another post, but if you are curious and know the basics you can go ahead and look at Graph Stitching.

What is Graph QL?

Hot chocolate demo — Dotnet

Photo by Nica Cn on Unsplash

For doing GraphQL with Dotnet core, you can use a package called HotChocolate.

A simple hello world with an Empty web API project

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

We can then access the playground via “/playground”:

GraphQL hello world

The order summary graph

Returning the customer profile:

If you test it this in the playground, you should see the “Orders” property coming as empty.

Just to remind you can check what is your schema through that little tab on the right:

Schema tab “playground”

Resolving orders:

Loading products in batch:

REST to Graph — Subtle differences

Photo by sebastiaan stam on Unsplash

The Graph specification has a few differences with REST that might trick you while developing:

Exceptions might not result in 500 — Internal Server Error

Instead of changing the status code, the response will contain an object with “errors”:

The Graph query is not JSON

But if you inspect the request that we are doing in the “/playground”, you will see the server is receiving application/JSON in the POST request body, with the query property containing the Graph request.

Further points

Useful links:


“GitHub chose GraphQL for our API v4 because it offers significantly more flexibility for our integrators. The ability to define precisely the data you want — and only the data you want — is a powerful advantage over the REST API v3 endpoints.”