Creating GraphQL API with C#

GraphQL offers one of the most effective ways to build APIs specially when it comes to mobile apps. In this article I talk about how to use my package to quickly create GraphQL APIs.

This article is not to about learning GraphQL itself but helps a C# developer use GraphQL without needing to go through lengthily tutorials or courses — like I originally did myself. For detailed information about GraphQL see its official website.

Introduction

GraphQL was originally introduced by Facebook to be used by React based clients. For people who know React is comes in two flavors: React.JS used to create SPA web applications and React.Native used to build native mobile apps. Both of these technologies are created on top of JavaScript. Facebook website and mobile apps are themselves created using React.

In order to provide an effective way to create APIs to be consumed by the client apps, Facebook introduced GraphQL which was also implemented in JS and could be used as an alternative to node.js to build APIs by JS programmers.

GraphQL APIs offers two major advantages over REST APIS:

1. Using GraphQL the caller can specify what specific properties of an object it is interested in.
2. If offers a subscription mechanism to update the client in a real-time fashion.

The first item is specifically important for mobile apps. Mobile apps have limited bandwidth — at least before 5G — and therefore they rather to have more chatty-oriented conversations with the server. GraphQL allows the client to specifically choose what properties to receive in a very easy way. The heavy lifting to filter is done behind the scene by GraphQL. Figure below shows an example GraphQL query to retrieve each book’s name, and first and last name of the author.

{
   book {
      name
      authors {
         firstName,
         LastName
      }
   }
}

This is also very beneficial to backend developers. If you have tried to create REST APIs using ASP.NET, you have probably come across a situation wondering whether you should return sub types or have a separate controller for them. With GraphQL you don’t need to worry about that. You can simply return the entire object graph and let the client filter out what they don’t need.

The second item is something that does not come with ASP.NET templates. Being able to receive real-time updates on changes to data — called graph updates in GraphQL language— requires relying on duplex transport mechanism like SignalR or WebSockets. Anybody who have tried to use these technologies, knows it is not straight forward and easy to use them. GraphQL offers this free of charge using subscriptions. Figure below shows how you can subscribe to an order change:

There are other advantages in using GraphQL like auto-generated API schema and documentation, GraphiQL playground to try APIs that we don’t go through them here.

Using GraphQL in C#

The main NuGet package created to use GraphQL is by an amazing C# developer called Joe McBride. The code for GraphQL.net can be found here. He has done an exemplary job at the protocol-level to implement queries, mutations — updates are called mutations in GraphQL language — , and subscriptions. However, using the package as is requires a lot of coding. For example, for each model type, we need create up to 6 extra types, one for inhering from each GraphQL base class that allows the type to be used each type of operation plus and an extra class to send the request. When I first tried it and made it work I was both excited and exhausted. Excited to see it working but exhausted to see how much extra had to be done to make it work.

My NuGet package wraps Joe’s package and uses reflection to generate all the required type under the hood. Using the package, you only need to do 3 things:

1. Register the types you would like to expose . For example in ASP.NET you can do this in ConfigureServices method. In a console or WPF app you could do it in your Main method or window. Note that you can optionally pass a Boolean to control whether the type can be changed by the client or not.

2. Mark the exposed properties using API attributes. You can also pass a Boolean here to control mutability at the property level.

3. Define your operations like you would have done without this package. Note that I am using another class of mine called singltonDataContext that allows the scope of the Data Context be singleton — when you register a DataContext class in ASP.NET it’s defined at the session scope.

To see the code for this package and also see a functional example see the related GitHub repo.