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

8 min readNov 29, 2020

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

REST is a single entity focused with URLs as:

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:

Imagine you are building an order summary page for an e-commerce, for that you need the customer orders, list each order total price, items purchased including quantity, unit cost and product name.

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

This is how an implementation would look like in GraphQL:

GraphQL playground — Order summary query

Diagram with the user browser only connecting to Graph Service

Advantages

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?

GraphQL is a specification of a query language for APIs and a runtime for fulfilling those queries with your existing data.

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

Add the required packages:

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

The full code is here, but if you were doing this step by step:

Returning the customer profile:

Amend the Query.cs to include a method to retrieve a customer.

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:

For telling HotChocolate how to resolve the Orders property of the customer, we can add a Resolver as:

Loading products in batch:

Remember we had that problem of N calls to fetch products, GraphQL solves this with BatchDataLoaders as:

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

Rather than returning a different status code when things go wrong, the Graph QL specification still returns 200 OK, because the status code is used as a transport layer concern, not the GraphQL layer.

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

The Graph query is not JSON

Just remember the Graph request isn’t JSON, so you don’t need to add commas and double-quotes.

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

A GraphQL API isn’t only for reading data, you can make changes using mutations (Equivalents to POST, PUT and Patch) and even listen to events using subscriptions, which are things I plan to cover in further posts.

Useful links:

Conclusion

So it’s REST dead and obsolete? I wouldn’t say so, GraphQL is a tool for you to add to your toolbox, so you can evaluate the pros and cons once planning for a new API. Just keep in mind some big names are moving towards Graph as GitHub, and in their own words:

“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.”