GraphQL In .NET Core Web API With Entity Framework Core - Part Five

In this article, we will see different query formats, the way of using a directive in a query, and the process of defining variables in the query.

So far, we have seen GraphQL queries on a single table, multiple tables, and query with parameters in this article series.

Today, we will discuss the below items in detail.
  1. Aliases
  2. Multiple Queries
  3. Fragment
  4. Named Queries
  5. Variables
  6. Directive
  7. Optional Parameter

Aliases

Consider a scenario where you have exposed your APIs using GraphQL to multiple clients. Let’s take our existing example that we are going to expose - employee entity with certifications via API to multiple clients. Now each client wants their own naming convention for properties in an entity. One client may ask that I should get a certificate as a response; not the title. The other client may expect CertificationName as a response rather than a title, so we can’t create client specific APIs. In this situation, GraphQL alias feature will help. We need to ask the client to send alias along with the query, i.e., whatever the name they want, they just need to pass in the query and GraphQL will return the response accordingly.

In the below sample query, we have passed Employee as an alias for employee and CertificationName as the alias for title.

GraphQL In .NET Core Web API With Entity Framework Core 

We can compare query and query response with alias and without alias for better understanding. 

Query / Alias Without Alias With Alias
Query
  1. {  
  2.   employees{  
  3.     name  
  4.     certifications  
  5.     {  
  6.       title  
  7.     }  
  8.   }  
  9. }  

  1. {  
  2.   Employee:employees{  
  3.     name  
  4.     certifications  
  5.     {  
  6.       CertificationName:title  
  7.     }  
  8.   }  
  9. }  

Query Response
  1. {  
  2.   "data": {  
  3.     "employees": [  
  4.       {  
  5.         "name""Akshay",  
  6.         "certifications": [  
  7.           {  
  8.             "title""MCSD"  
  9.           }  
  10.         ]  
  11.       },  
  12.       {  
  13.         "name""Panth",  
  14.         "certifications": [  
  15.           {  
  16.             "title""Scrum Master"  
  17.           }  
  18.         ]  
  19.       }  
  20.     ]  
  21.   }  
  22. }  

  1. {  
  2.   "data": {  
  3.     "Employee": [  
  4.       {  
  5.         "name""Akshay",  
  6.         "certifications": [  
  7.           {  
  8.             "CertificationName""MCSD"  
  9.           }  
  10.         ]  
  11.       },  
  12.       {  
  13.         "name""Panth",  
  14.         "certifications": [  
  15.           {  
  16.             "CertificationName""Scrum Master"  
  17.           }  
  18.         ]  
  19.       }  
  20.     ]  
  21.   }  
  22. }  


Multiple Queries

In some scenarios, you want to execute more than one query and expect the result as single json, you can do the same by giving an alias. I have given aliases like E1 & E2 and written two different queries, one to fetch employee1 and another to fetch employee2 and you can see in the response that both the employees are added in the single JSON file.

GraphQL In .NET Core Web API With Entity Framework Core 

Query

  1. {  
  2.   E1:employee(id:1){name certifications {title}}  
  3.   E2:employee(id:2){name certifications {title}}  
  4. }  

Query Response

  1. {  
  2.   "data": {  
  3.     "E1": {  
  4.       "name""Akshay",  
  5.       "certifications": [  
  6.         {  
  7.           "title""MCSD"  
  8.         },  
  9.         {  
  10.           "title""Scrum Master"  
  11.         }  
  12.       ]  
  13.     },  
  14.     "E2": {  
  15.       "name""Panth",  
  16.       "certifications": [  
  17.         {  
  18.           "title""MCT"  
  19.         },  
  20.         {  
  21.           "title""PMP"  
  22.         }  
  23.       ]  
  24.     }  
  25.   }  
  26. }  

Fragment

In multiple queries, if you observe closely, we have added {name certifications {title}} which we want as a response, we have written multiple times. Now, assume that you want to write similar kinds of queries around 10 or 20 times, then you need to write the same in the query that many times. In order to avoid such repetitions, we can use fragment. You can write fragment on type; i.e., EmployeeType, and define what you want as a response once, and pass the same fragment in each query with three dots (…) as a prefix and you will get the same response.

GraphQL In .NET Core Web API With Entity Framework Core 

Query

  1. {  
  2.   E1:employee(id:1){...employeeList}  
  3.   E2:employee(id:2){...employeeList}  
  4. }  
  5.   
  6. fragment employeeList on EmployeeType{  
  7.   name, certifications {title}  
  8. }  

Query Response

  1. {  
  2.   "data": {  
  3.     "E1": {  
  4.       "name""Akshay",  
  5.       "certifications": [  
  6.         {  
  7.           "title""MCSD"  
  8.         },  
  9.         {  
  10.           "title""Scrum Master"  
  11.         }  
  12.       ]  
  13.     },  
  14.     "E2": {  
  15.       "name""Panth",  
  16.       "certifications": [  
  17.         {  
  18.           "title""MCT"  
  19.         },  
  20.         {  
  21.           "title""PMP"  
  22.         }  
  23.       ]  
  24.     }  
  25.   }  
  26. }  

Named Queries

Now in the case where you want to write required queries and execute as and when it's required, you can write named queries, which  means give the name of each query so that while executing it will ask which one you want to execute. Refer to the the below screen shot for the reference. The syntax for this is query {queryName} followed by {Actual Query}

GraphQL In .NET Core Web API With Entity Framework Core 

Query

  1. query all  
  2. {  
  3.   employees {name certifications {title}}  
  4. }  
  5. query E1  
  6. {  
  7.   E1:employee(id:1){name, certifications {title}}  
  8. }  

Query Response for ‘all’

  1. {  
  2.   "data": {  
  3.     "employees": [  
  4.       {  
  5.         "name""Akshay",  
  6.         "certifications": [  
  7.           {  
  8.             "title""MCSD"  
  9.           },  
  10.           {  
  11.             "title""Scrum Master"  
  12.           }  
  13.         ]  
  14.       },  
  15.       {  
  16.         "name""Panth",  
  17.         "certifications": [  
  18.           {  
  19.             "title""MCT"  
  20.           },  
  21.           {  
  22.             "title""PMP"  
  23.           }  
  24.         ]  
  25.       }  
  26.     ]  
  27.   }  
  28. }  

Query Response for ‘E1’

  1. {  
  2.   "data": {  
  3.     "E1": {  
  4.       "name""Akshay",  
  5.       "certifications": [  
  6.         {  
  7.           "title""MCSD"  
  8.         },  
  9.         {  
  10.           "title""Scrum Master"  
  11.         }  
  12.       ]  
  13.     }  
  14.   }  
  15. }  

Syntax to call Named Queries from Postman

URL https://localhost:44332/graphql
Method POST
Header Application/json
Request Body
  1. {  
  2. "query":"query all  
  3.                 {  
  4.                   employees {name certifications {title}}  
  5.                 }  
  6.          query E1  
  7.                 {  
  8.                   E1:employee(id:1){name, certifications {title}}  
  9.                 }",  
  10. "OperationName":"all"  
  11. }  

Response
  1. {  
  2.     "data": {  
  3.         "employees": [  
  4.             {  
  5.                 "name""Akshay",  
  6.                 "certifications": [  
  7.                     {  
  8.                         "title""MCSD"  
  9.                     },  
  10.                     {  
  11.                         "title""Scrum Master"  
  12.                     }  
  13.                 ]  
  14.             },  
  15.             {  
  16.                 "name""Panth",  
  17.                 "certifications": [  
  18.                     {  
  19.                         "title""MCT"  
  20.                     },  
  21.                     {  
  22.                         "title""PMP"  
  23.                     }  
  24.                 ]  
  25.             }  
  26.         ]  
  27.     }  
  28. }  

Variables

So far we have written queries where we were passing hard coded values for the employeeid, here we can create a variable which can accept the value dynamically and return the response accordingly. 

With the query name we need to mention variable; i.e., $employeeId and make it mandatory using the ! symbol. Replace hard coded employee id value with the variable; i.e., $employeeId. Before executing the query we need to pass employeeId value as Query Variables.

GraphQL In .NET Core Web API With Entity Framework Core

Query

  1. query E1($EmployeeId : ID!)  
  2. {  
  3.   employee(id:$EmployeeId){name, certifications {title}}  
  4. }  

Query Variables

  1. {  
  2.   "EmployeeId": 2  
  3. }  

Query Response

  1. {  
  2.   "data": {  
  3.     "employee": {  
  4.       "name""Panth",  
  5.       "certifications": [  
  6.         {  
  7.           "title""MCT"  
  8.         },  
  9.         {  
  10.           "title""PMP"  
  11.         }  
  12.       ]  
  13.     }  
  14.   }  
  15. }  

Syntax to call Named Queries from Postman

URL https://localhost:44332/graphql
Method POST
Header Application/json
Request Body
  1. {  
  2. "query":"query all  
  3.                 {  
  4.                   employees {name certifications {title}}  
  5.                 }  
  6.                   
  7.          query E1($EmployeeId:ID!)  
  8.                 {  
  9.                   employee(id:$EmployeeId){name, certifications {title}}  
  10.                 }",  
  11. "OperationName":"E1",  
  12. "variables":{"EmployeeId":2}  
  13. }  

Response
  1. {  
  2.     "data": {  
  3.         "employee": {  
  4.             "name""Panth",  
  5.             "certifications": [  
  6.                 {  
  7.                     "title""MCT"  
  8.                 },  
  9.                 {  
  10.                     "title""PMP"  
  11.                 }  
  12.             ]  
  13.         }  
  14.     }  
  15. }  

Directive

Consider a scenario where your expectation is to get a response based on your query parameter, for example if value for Boolean parameter is passed as true then return a long description, or else don’t consider a long description in response. So declare a variable which expects true or false, which means a long description needs to be returned or not. And along with a long description in the query we can use inbuilt directive; i.e., @include(if: {condition}).

GraphQL In .NET Core Web API With Entity Framework Core 

Query

  1. query all($ShowLongDescription : Boolean!)  
  2. {  
  3.   employees  
  4.   {  
  5.     id  
  6.     name  
  7.     email  
  8.     mobile  
  9.     address  
  10.     shortDescription  
  11.     longDescription @include(if: $ShowLongDescription)  
  12. }  
  13. }  

Query Variables

  1. {  
  2.   "ShowLongDescription":  false  
  3. }  

Query Response

  1. {  
  2.   "data": {  
  3.     "employees": [  
  4.       {  
  5.         "id": 1,  
  6.         "name""Akshay",  
  7.         "email""akshayblevel@gmail.com",  
  8.         "mobile""9999999999",  
  9.         "address""Hyderabad",  
  10.         "shortDescription""Short Description"  
  11.       },  
  12.       {  
  13.         "id": 2,  
  14.         "name""Panth",  
  15.         "email""panth@gmail.com",  
  16.         "mobile""8888888888",  
  17.         "address""Vadodara",  
  18.         "shortDescription""SD"  
  19.       }  
  20.     ]  
  21.   }  
  22. }  

Optional Parameter

In the continuation of the above directive implementation, we can declare parameter as optional. For example, if someone doesn’t pass the expected value, in that case also it should work. So we have passed false as default parameter value. If you don’t pass value for showLongDescription it won’t return longDescription by default. If you want to get longDescription in your response, you need to pass parameter value as true.

GraphQL In .NET Core Web API With Entity Framework Core 

Query

  1. query all($ShowLongDescription : Boolean=false)  
  2. {  
  3.   employees  
  4.   {  
  5.     id  
  6.     name  
  7.     email  
  8.     mobile  
  9.     address  
  10.     shortDescription  
  11.     longDescription @include(if: $ShowLongDescription)  
  12. }  
  13. }  

Query Response

  1. {  
  2.   "data": {  
  3.     "employees": [  
  4.       {  
  5.         "id": 1,  
  6.         "name""Akshay",  
  7.         "email""akshayblevel@gmail.com",  
  8.         "mobile""9999999999",  
  9.         "address""Hyderabad",  
  10.         "shortDescription""Short Description",  
  11.         "longDescription""Long Description"  
  12.       },  
  13.       {  
  14.         "id": 2,  
  15.         "name""Panth",  
  16.         "email""panth@gmail.com",  
  17.         "mobile""8888888888",  
  18.         "address""Vadodara",  
  19.         "shortDescription""SD",  
  20.         "longDescription""LD"  
  21.       }  
  22.     ]  
  23.   }  
  24. }  

GraphQL In .NET Core Web API With Entity Framework Core

Query

  1. query all($ShowLongDescription : Boolean=false)  
  2. {  
  3.   employees  
  4.   {  
  5.     id  
  6.     name  
  7.     email  
  8.     mobile  
  9.     address  
  10.     shortDescription  
  11.     longDescription @include(if: $ShowLongDescription)  
  12. }  
  13. }  

Query Variables

  1. {  
  2.   "ShowLongDescription":  true  
  3. }  

Query Response

  1. {  
  2.   "data": {  
  3.     "employees": [  
  4.       {  
  5.         "id": 1,  
  6.         "name""Akshay",  
  7.         "email""akshayblevel@gmail.com",  
  8.         "mobile""9999999999",  
  9.         "address""Hyderabad",  
  10.         "shortDescription""Short Description",  
  11.         "longDescription""Long Description"  
  12.       },  
  13.       {  
  14.         "id": 2,  
  15.         "name""Panth",  
  16.         "email""panth@gmail.com",  
  17.         "mobile""8888888888",  
  18.         "address""Vadodara",  
  19.         "shortDescription""SD",  
  20.         "longDescription""LD"  
  21.       }  
  22.     ]  
  23.   }  
  24. }  

I hope this will help you guys during your GraphQL implementation.