GraphiQL in ASP.NET Core
Posted on Thursday, 10th August 2017
Having recently attended a talk on GraphQL and read about GitHib’s glowing post surrounding choice to use GraphQL over REST for their API, I was interested in having a play to see what all of the fuss was about. For those that aren’t sure what GraphQL is or where it fits in the stack let me give a brief overview.
What is GraphQL?
GraphQL is a query language (hence QL in the name) created and open-sourced by Facebook that allows you to query an HTTP (or other protocols for that matter) based API. Let me demonstrate with a simple example:
Say you’re consuming a REST API on the following resource identifier:
The response returns on this URI is the following JSON object is:
"Occupation": "Pied Piper CEO",
Now as a mobile app developer calling this service you’re aware of the constraints on bandwidth users face when connected to a mobile network, so returning the whole JSON blob when you’re only interested in their
Surname properties is wasteful, this is called over-fetching data, GraphQL solves this by letting you as a consumer dictate your data needs, as opposed to having it forced upon you by the service.
This problem is a fundamental requirement that REST doesn’t solve (in fairness to REST, it never set out to solve this problem, however as the internet has changed it’s a problem that does exist).
This is where GraphQL comes in.
Using GraphQL we’re given control as consumers to dictate what our data requirements are, so instead of calling the aforementioned URI, instead we
POST a query to a GraphQL endpoint (often
/graphql) in the following shape:
Our Web API powered GraphQL server fulfills the request, returning the following response:
This also applies to under-fetching which can best be described as when you have to make multiple calls to join data (following the above example, retrieving the
RoleId only to then call another endpoint to get the
Role information). In GraphQL’s case, we could represent that with the following query, which would save us an additional HTTP request:
The GraphQL query language includes a whole host of other functionality including static type checking, query functions and the like so I would recommend checking it out when you can (or stay tuned for a later post I’m in the process of writing where I demonstrate how to set it up in .NET Core).
So what is GraphiQL?
In fact, I’d suggest you taking a moment to go try a live exampe of GraphiQL here and see how GraphQL’s static type system and help you discover data that’s available to you via the documentation and intellisense. GitHub also allow you to query your GitHub activity via their example GraphiQL endpoint too.
Now you no longer need to worry about taking a dependency on Node or NPM in your ASP.NET Core solution and can instead add GraphiQL support via a simple middleware calls using GraphiQL.NET (before continuing I feel it’s worth mentioning all of the code is up on GitHub.
Setting up GraphiQL in ASP.NET Core
You can install GraphiQL.NET by copying and pasting the following command into your Package Manager Console within Visual Studio (Tools > NuGet Package Manager > Package Manager Console).
Alternatively you can install it using the .NET Core CLI using the following command:
dotnet add package graphiql
From there all you need to do is call the
UseGraphiQl(); extension method within the
Configure method within
Startup.cs, ensuring you do it before your
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
Now when you navigate to
/graphql you should be greeted with the same familiar GraphiQL screen but without the hassle of having to add node or any NPM packages to your project as a dependency - nice!
The library is still version 1 so if you run into any issues then please do feel free to report them!
Enjoy this post? Don't be a stranger!
Follow me on Twitter at @_josephwoodward and say Hi! I love to learn in the open, meet others in the community and talk Go, software engineering and distributed systems related topics.