Setup a GraphQL API using ASP.NET Core
A short guide on how to setup your own GraphQL API using ASP .NET Core
In this tutorial, I’m going to show you how you can create your GraphQL API using ASP .NET Core. The same setup can be followed for .NET Framework.
Note: You will need Visual Studio 2017 with the “.NET Core cross-platform development” workload installed.
Let’s jump right to it. Open up Visual Studio and let’s create a new ASP.NET Core Web Application. I have chosen the empty template.
Since I’ve started with an empty project, let’s add our project structure. First I’m going to add all of the relevant folders. Controllers, Models and Query.
Disclaimer: I will not be following my best practices. I’m omitting the use of DI for the sake of keeping things simple.
Let’s create our GraphQLQuery.cs file in our Query folder
This will be the query object we will be taking in from GraphQL clients. I believe the properties in this object are self explanatory; a valid request may contain a
Query or an
OperationName depending on the use of it. Checkout the official documentation for more information on the request.
Before we move any further, let’s install our nuget packages. From the Package Manager or the console, add the following nuget packages:
You read that correctly, we’re install both
GraphQL (for setting up GraphQL) and
GraphiQL (for giving us a sandbox to run queries from within the browser and view API documentation).
We’ll be using Entity Framework Core for storing and using the data. Let’s install that also.
If you haven’t used EF, head over to the Microsoft website to learn more about it.
Let’s get started with our Models. Our application will contain a list of Restaurants, the Restaurant Menu, and the Menu Items.
Head over to the Models folder and let’s add the following:
I am not going to go over these classes but they all contain some information about what they represent.
These models will be used for our application context (our data store). Entity Framework uses naming conventions to create links between these models, hence why we have
MenuId in the child models.
Let’s create our application context:
If you are familiar with Entity Framework, this is nothing special. We are just defining what our data store contains (which are our models).
Let’s create our GraphQLController in the Controllers folder
This controller only defines a single action
Post where we take in
GraphQLQuery object we have implemented earlier.
Variables property defined in the GraphQLQuery cannot be used as is, so we first need to extract the data out of it using the
ToInputs() extension provided by GraphQL.
We have defined our schema inline here but this can be extracted into it’s own file. This is also where you will be defining your Mutation object. I will not be going through mutations in this article but in essence, mutations are for manipulating the data whilst queries are for retrieving them.
We’re not done yet! In order for GraphQL to understand our models that we have defined, we need to define their types. Create a folder in the Models folder called GraphQL.
We now need to add RestaurantType, MenuType and MenuItemType.
This object implements the ObjectGraphType for the Restaurant model. In the constructor of this object, we define the name, and all of the fields that GraphQL will have access to.
Some of the field types are already understood by GraphQL, but for some, we need to instruct GraphQL on what they are. Id for example is a GUID. We pass in the type of the object to our
Field(...) function to inform it what to use for the type, in this case it’s the IdGraphType.
Menus property is a list of menus. We need to inform GraphQL that this will be a custom type. we do that by setting the type to
As you can see, we are also defining a description for every property. This allows us to build our API documentations.
Let’s do the same for the MenuType and MenuItemType.
We have finished defining our types. Let’s start with creating our queries. Create a new class in the Query folder called EatMoreQuery.
In this class, we define all of our queries. As this class gets bigger, I advise that you extract out every query into it’s own individual query.
We have two different queries here,
restaurant takes in a single parameter,
id, which we define and add a description to. In
resolve we extract out the id property and we make a query call to our data store,
AppContext , we then return the restaurant.
Because we have already defined the type of restaurant, GraphQL is able to determine the conversion from the
Restaurant object to the
I’m using the EntityFramework
include()function to allow GraphQL access to all of the child elements.
Note: Like I have mentioned before, I am not following best practices here and I do not advise the use of the data context like this within your application. Personally, I use the Service/Repository pattern with dependency injection to provide the application the ability to access/change my data.
restaurants query is similar to the
restaurant query. However, we don’t do any filtering on it and return the full list.
Let’s define some test data we can work with. I’m creating a DataSeed static class that can inject some static data to our application so that we can start querying it.
Finally, let’s make the required changes to the Startup.cs file.
First of all, I want to mention that I’m adding the AppContext using the
UseInMemoryDatabase("EatMoreDb") to ensure that the database runs in memory for the sake of keeping things simple for this article.
Configure method, we ensure that we are using GraphiQl with
useGraphiQl() extension from the
GraphiQL nuget package. we then run our data seed to ensure we have some data to play with. You don’t need to worry about the
serviceScope definitions. Essentially, I’m using resolving the AppContext from our serviceProvider.
That’s all we need to configure. If you hit F5, you should get something like this:
This is GraphiQL which provides us with a visual representation and environment to access GraphQL.
On the right hand side, we are able to see the documentation for our queries. You can click on the
EatMoreQuery to see the queries defined and what they return. We are also able to drill down to the properties of our objects that we are able to retrieve.
Let’s write our first query that will return a list of restaurants and their names.
Write this in the query window and you will see something like the following:
now let’s see what other queries we can make. Let’s run the
restaurant query and with the
id parameter. Copy the ID of the restaurant you see on your screen now and run the following:
Make sure you substitute the id of the restaurant you have on your screen.
We should now see the following:
What we have done so far was hard code the query of the restaurant id. What if we were getting this information from an external call? We can use the query variables in this case. In the query window, you can drag the Query Variables window into view.
Let’s write our query in a way that will allow us to take in parameters.
We are now defining a query
restaurant that takes in the
$id of type
ID! is an identifier that is required.
We now need to provide our query variable.
And there you go. GraphQL server setup in ASP.NET Core. Find the full source code here.