GraphiQL in ASP.NET Core

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:

GET service.com/user/1

The response returns on this URI is the following JSON object is:

{
    "Id": 1,
    "FirstName": "Richard",
    "Surname": "Hendricks",
    "Gender": "Male",
    "Age": 31,
    "Occupation": "Pied Piper CEO",
    "RoleId": 5,
    ...
}

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 FirstName and 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:

{
    Id,
    FirstName,
    Surname
}

Our Web API powered GraphQL server fulfills the request, returning the following response:

{
    "Id": 1,
    "FirstName": "Richard",
    "Surname": "Hendrix"
}

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:

{
    Id,
    FirstName,
    Surname,
    Role {
        RoleName
    }
}

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?

Now you know what GraphQL is, GraphiQL (pronounced ‘graphical’) is a web-based JavaScript powered editor that allows you to query a GraphQL endpoint, taking full advantage of the static type checking and intellisense promised by GraphQL. You can consider it the Swagger of the GraphQL world.

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.

Introducing GraphiQL.NET

Traditionally if you wanted to set this up you’d need to configure a whole host of node modules and JavaScript files to enable you to do this, however given .NET Core’s powerful middleware/pipeline approach creating a GraphiQL middleware seemed like the obvious way to enable a GraphiQL endpoint.

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).

Install-Package graphiql

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 AddMvc(); registration.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    app.UseGraphiQl();

    app.UseMvc();
}

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!