GraphQL

Background

GraphQL was developed by Facebook in 2012 and publicly released in 2015. The goal was to create an API query language that allowed clients to request the exact data they needed, reducing the following issues common with REST APIs:

• Over-fetching: Getting more data than you need, (e.g. I just need the users name, not their eye color etc.)
• Under-fetching: Not getting enough data, (e.g. I want the users name and the title of any related blog posts they’ve made)
  • With REST you may need to make multiple requests to different endpoints to get this information.

Unlike REST, where the server defines the shape and amount of data returned, GraphQL allows the client to specify the structure, leading to more efficient data retrieval, especially for complex or nested data.

How it works

1. Schema & Types

GraphQL revolves around a schema that defines the structure of the data that clients can request. The schema consists of types, which describe the shape of the objects and the fields clients can query, examples include but are not limited to:

• Scalars: Basic types like: String, Int, Boolean and ID.
• Objects: Represent entities like User, Order, or Product.
• Input Types: Objects used for supplying data - usually to mutations.

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post]
}

type Post {
  id: ID!
  title: String!
  body: String!
}

The bang (!) denotes that the field is non-null

The schema acts as self-describing API specification and documentation, clients can make an Introspection query to obtain the schema, and therefore have a complete understanding of the API calls they can make. Tools like Postman and Insomnia can ingest a GraphQL schema in this way, providing the user with functionality like auto-complete and in-line docs.

2. Queries

Clients use queries to request data. A GraphQL query specifies the shape of the response, asking for only the fields the client needs.

The following example shows the retrieval of a user with an ID of `, where we select only the users name and any posts that they may have made:

query 
{
  user(id: 1) {
  name
  posts {
    title
    }
  }
}

GraphQL APIs will most usually return a result set as JSON, as shown below for our example query:

{
  "data": {
    "user": {
      "name": "John",
      "posts": [
        { "title": "GraphQL Overview" }
      ]
    }
  }
}

3. Mutations

Mutations handle data-changing operations like creating, updating, or deleting entities. They resemble queries but allow modifications.

mutation {
  createUser(name: "Alice", email: "alice@example.com") {
    id
    name
  }
}

4. Subscriptions

Subscriptions are used for real-time updates pushed to the client. Typically implemented using WebSockets, the client can subscribe to events and automatically receive new data when the server publishes it.

GraphQL subscriptions have similarities with Webhooks.

subscription {
  userAdded {
    id
    name
  }
}

5. Transport

While the GraphQL specification does not stipulate that HTTP is used as the transport for GraphQL, the majority of GraphQL APIs will use HTTP for transport purposes. Unlike REST-based APIs however, GraphQL APIs will typically have only 1 HTTP POST endpoint that all requests are sent to, (request detail such as a specific query are supplied in the Body of the HTTP POST request).

REST API’s usually have multiple endpoints for each resource type, split further by HTTP Verb for the operation type, including but not limited to: Read (GET), Create (POST) and update (PUT & PATCH).

GraphQL in .NET

At the time of writing Microsoft do not provide native GraphQL frameworks for either the serving of GraphQL APIs, or their consumption as a client.

You can of course still consume a GraphQL API using just native Microsoft packages as you typically only need to make a HTTP POST request to the API. You will have to structure the body of that request in a specific way for the API call to resolve, which is where a native GraphQL client would make this easier.

.NET GraphLQ Servers

The following are 2 of the more popular GraphQL server packages for .NET, for a more complete list refer to the GraphQL website.

• graphql-dotnet
• Hot Chocolate

I made a video building out a GraphQL API using Hot Chocolate with .NET 5, so while it’s probably a little out of date, most of the theory will still be accurate:

.NET GraphQL Clients

• GraphQL.Client
• Strawberry Shake

For a more complete list refer to the GraphQL Docs

Further Reading

• GraphQL Website