Skip to content →

Introduction to GraphQL and Designing Simple Query API with ASP.NET Core 2.0

Hi, all.

I couldn’t find enough time to write a new article for a few months. In fact, I wrote some part of this article in August, but I could not complete it. 🙂 Finally, I did!

Anyway, I guess GraphQL (at the same time ASP.NET Core 2.0) is among the most popular topics of recent times on data access and query operations. Against the rapidly developing business needs of today, GraphQL especially provides us the ability to develop applications rapidly and efficiently by leaving the data access and advanced query operations to the client-side.

First, is new for me. I don’t have any production experience on it yet. But, especially for our mobile API‘s, we’re planning to use data access and query operations with GraphQL as a gateway. (Currently, we’re using it at test phase.)

In this article, I’ll try to show based on my some experience how we can perform query operations efficiently in the ASP.NET Core 2.0 using the GraphQL.

So, Why GraphQL?

Before I answer the why GraphQL question, I want to mention a topic. A lot of people say REST will die and GraphQL will be the new generation. I personally don’t agree with this idea. My idea is REST and GraphQL shouldn’t be confused with each other.

First, it is possible to use both REST and GraphQL together. In addition, if GraphQL is used at the right time and right business needs, it provides the data access and querying flexibility to the clients. (Especially for the mobile side)

Now, let’s talk about the why GraphQL question. In today’s technologies, it is obvious that the usage rate of mobile applications is quite high. Usually most online users were almost mobile users, at the companies I have worked with. If we look at the development side, we use APIs that form the building blocks of our applications for both web and mobile sides.

At this point, we’ll face some other challenges on mobile side relative to size of data we receive, battery consumption and network traffic. Usually, a quick workaround is to choose to implement a Gateway API to perform aggregation operations in there instead. Unfortunately, story goes on and now we face versioning and backward compatibility issues as we implement new features.

There are some advantages GraphQL provides to us, such as:

  • It provides the ability to retrieve the data with a single request to clients
  • It reduces the need for tailored endpoints such as API gateways which doing data aggregation operations
  • Most importantly, the teams are able to develop rapidly and easily

In addition to rapidly and easily development topic, development teams of many companies are divided into small domains, and each team develops the application in their own responsibilities. It was like this at the companies I work with.

Let’s think, we need product detail of the id “1“. Normally, in a RESTful API, we can retrieve the product detail with a GET request from the endpoint “api/products/1“. But, the mobile team needs to the just “name“, “description” and “price” fields on the product detail, and in addition to that, also needs to the “id” and “name” fields on the product category detail.

Usually, we have two different options we can do.

  1. We can do two different requests – roundtrips! (I don’t think so we can choose to do roundtrips while the topic is about the mobile side)
  2. Or we can create a tailored endpoint

In addition to this, if each team has its own sprints, at this point, the mobile team will also wait for the other team which are responsible from the development of the Product API. In this age of technology, of course, we want to add new features quickly, isn’t it?

In this case, if the GraphQL is used, the mobile team will be able to retrieve the requested data, with a single request efficiently and to develop feature rapidly without the depending on the other team.

Let’s look at the following sample GraphQL query to retrieve product and category details:

The client can retrieve the requested data easily with a single query as the above.

NOTE: Of course, we can provide these operations with a RESTful API. (Querying, filtering, sorting, etc…) But, the requested features always should be developed and implemented in the RESTful API or handled by the client side. (Response aggregations etc…) At this point, while the GraphQL comes into prominence, we shouldn’t forget that GraphQL needs to have a correct mapping structure to be able to do what we want.

Implementation in ASP.NET Core 2.0

Now we’ll design a basic sample API that includes the “product” and “category” for the implementation phase.

First let’s create a new ASP.NET Corewebapi” project with the following code line.

After creation of the project, create a new folder called “Models” and add “Category” and “Product” models into the that.

And now, we need to create a “Data” folder, and add “ICategoryRepository” and “IProductRepository” interfaces into the that.

Let’s implement these interfaces with a few sample data like as below.

We defined the models and repositories, now we can start to implementation .NET client of GraphQL.

Let’s include the GraphQL package from the NuGet to the project with the following code line.

After including the package to the project, firstly we will create Object Types of GraphQL. Object types and fields are the main components of GraphQL schema. This means it specifies which object we can get through the service that we will create and what fields it has.

Now we will create two ObjectGraphType into the “Models” folder, and these are “CategoryType” and “ProductType” classes.

If we look at the two classes, each class derived from the “ObjectGraphType” class. In here, we defined the requested fields using the fluent methods of GraphQL library. And then, we defined the resolve functions for the relations.

Let’s create a root type to use the query operations. For that, create a new class called “EasyStoreQuery“.

In the “EasyStoreQuery” root type, we configured the schema like in the “CategoryType” and “ProductType“. By the way, with the “arguments” parameter, we have also specified the query arguments.

NOTE: Instead of configuring the category or product repositories as the source of the “resolve” function in the “CategoryType“, “ProductType” and “EasyStoreQuery“, we could configure the REST endpoints.

Okay, now we can create the schema which will describe the structure of the data. First, let’s create a new class called “EasyStoreSchema“, and then derive it from the “Schema” class.

There are two types of schema has. First one is the “Query” and the other one is “Mutation” type. At this point, we used the only “Query” type. When we inject the “EasyStoreSchema” class, we will pass the “EasyStoreQuery” type as a parameter.

Now there are two last things that we have to do. First one is to prepare GraphQL endpoint, another one is to perform service injection operations. So, let’s create a request class called “GraphQLQuery” into the “Models” folder as below.

After creating the request object, we can prepare the controller. Therefore, create a “GraphQLController” class as following below.

First, we specified the endpoint using the route attribute and then injected the “IDocumentExecuter” and “ISchema” interfaces. At this point, the “IDocumentExecuter” will execute the “ExecutionOptions” parameter to create the data that the client wants. Btw, client-driven application development looks like great, isn’t it?

Now, the last thing is the dependency injection. Let’s inject the services in the “Startup” class as follows.

That’s all.

Okay, let’s test it! We need to start the project using “dotnet run” command and a few tests.

NOTE: I used the “Postman” to an API call.

Let’s POST the following query to the GraphQL endpoint and see the result.

If we look at the response, we can see the “id” and “name” fields of the category “1” as we see below.

So, what if we want to get products of this category with the “id“, “name” and “price” fields? It’s easy! All we have to do is modify our query as follows.

And the response is:


I really enjoyed while playing GraphQL for PoC. At this point, my opinion is, if our database schema and APIs design are suitable for use as a resource, GraphQL can be a good choice for the client-driven application development. On the other hand, GraphQL provides to reduce the size of the data between the server and the client.

Sample project:


Bu makale toplam (8210) kez okunmuştur.


Published in ASP.NET Core GraphQL


  1. Kerim Kerim

    Güzel paylaştım. Teşekkürler

  2. Hüseyin Hüseyin

    Paylaşımız için teşekkür ederim ama kafamda oturmayan şeyler var 🙂
    GraphQL kullanarak web service üzerinde herhangi bir değişiklik yapmadan hızlıca bir query oluşturup istediğimiz columnları tanımlayarak data getirme işlemleri yapabiliyoruz, bu işlem bize ortam bazında avantajlar sağlıyor(response data size or extra columns).

    Peki burada bir spesifik bir filter vermek istediğimizde web service burada nasıl davranıyor. Örneğin şurada bir örnek var;
    Queryde belirttiğimiz filter tanımları bir repository aracılığıyla db seviyesindemi filter yapıyor yoksa repositoryde örneğin GetProducts() methodundan dönen liste içerisindemi bir filter uyguluyor?

    Bu konuda biraz detay verebilir misiniz? Artı ve eksileri varmıdır?

    • Merhaba, teşekkür ederim öncelikle yorumunuz için. Bu işlemler aslında sizin ilgili source’u ve query argument’ları nasıl tanımladığınıza göre biraz değişiklik gösteriyor. Hatta relation’ların resolve kısımlarına yönelik bunun üzerine tartışılmış bir çok N+1 query sorusu, query optimizasyon vb. gibi çözümleri de mevcut. (Benim gördüğüm) Benim yapmış olduğum basit örnekte “id” argument’ı ile ilerlediğim için bir filtering söz konusu değil db tarafında, in-memory gerçekleşmektedir. Buradaki query argument’larını çoğaltabilir ve ya kendi query argument’larımız için graph type’lar oluşturabilir ve spesifik filter query’leri geçebilerek, predicate’ler ile de bir sorgu oluşturabiliriz db’ye hit etmeden önce veya ilgili servis’in bir filter endpoint’i varsa. Bu kullanmış olduğum .NET client’ı hala geliştirilmekte olan bir paket, ayrıca benim için de baya yeni bir konu süredir üzerinde çalışıyorum bu tarz concern’lere karşı, deneyimlerimi buradan paylaşmaya devam edeceğim.

      • Hüseyin Hüseyin

        Terimler arasında kaybolup gittim ama konuyla ilgili yeni makalelerinizi merakla bekliyorum 🙂
        Ama özetle istemciden sunucudaki ilgili endpointe gelen request içerisindeki filtreyi bir convert işlemiyle ilgili orm tool yada data çekmek için kullandığımız data toolu ne ise, onun filter yapısına uydurup data çekmek işi çözecektir diye anlıyorum. Tabi bu convert işlemindeki pradicateleri uyumlu bir şekilde otomatik çeviren bir modül yoksa durum biraz vahim olabilir.

        • Merhaba tekrar, evet. 🙂 Örnek vermek gerekirse eğer: “EasyStoreQuery” içerisindeki argument’lere bakarsak, “new QueryArgument {Name = “id”, Description = “Category id”}” şeklinde bir id parametresi ekliyoruz aslında. GraphQL’in .NET client’ı ile buraları şekillendirmek bize kalıyor biraz. 🙂 Bende üzerinde çalışmaktayım halen, ilerleyen bölümlerde paylaşmaya devam edeceğim edinebildiğim farklı tecrübeleri. 🙂

  3. son son

    Paylaşım için teşekkürler güzel açıklama. Ben yinede grapql in neden kullanılması gerektiğini tam anlayamadım. Linq le çekip filtring yapmamızdan bir farkı yok gibi görünnüyor. Belki burda linq expressioni direk mobilden geliyomuş gibi düşünebiliriz. Buda mobilci için backend geliştirme beklemesini azaltır gibi.

  4. praneet praneet

    Thanks ! Great post. Exactly what I was looking for.

  5. Gin Gin

    So how to return a list Products?

    • Hi Gin, What you mean by “a list Products”? We already return product list with the following query:


      If you want to return a product list without category, you should implement it in “EasyStoreQuery” query class without “id” parameter. Then you can be querying.

  6. Paul Paul

    Great write up and project. Thank you for your time explaining this.

Leave a Reply

Your email address will not be published. Required fields are marked *