GraphQL Day 000 : Introduction to Building Blocks

In this series of articles, we will walk through GraphQL and understand its importance in modern applications. Introduced by Facebook, and later moved to newly established GraphQL foundation, GraphQL has become integral part of modern applications.

Day 00 : Introduction to the building blocks

Day 01: Creating your first GraphQL server with HotChocolate

Day 02 : Type Definition Basics

Day 03 : Defining Mutations

Why GraphQL ?

GraphQL is a query language for modern web app, which allows clients to specify exactly what it requires from APIs. Traditional REST APIs can end up under-fetching or over-fetching through the set of endpoints it exposes. In some cases ,the client application might require multiple round trips to fetch the information because of the limitations in the exposed APIs. In some other cases, the client information might end up with more information than it requires, and would have to spend effort in parsing the require information – not to forget the overhead of extra information passed over the wire.

This is where GraphQL comes into play. GraphQL allows client application to precisely define the information it requires from the API. In other words, GraphQL provides a syntax that describes how to query for data, though not limited to it. It can also support CRUD operations using mutations. We will get to it soon.

The key steps towards creating your GraphQL service are

• Define Types
• Define Fields on the type
• Define functions on each type

A typical query in GraphQL would like the following

schema {
 query: ProjectQuery
}

type ProjectQuery {
 projects: [Project!]!
}

type Project {
 id: Int!
 name: String!
 createdBy: String!
}

The above describes a schema in its simplest form. The schema contains a query ProjectQuery. The ProjectQuery contains an array of Type Project. The ‘!’ character signifies the field is non-nullable. The type Project contains 3 fields, id (of type Int), name (of type String) and createdBy(of type String).

Let us consider a sample query and result.

// Sample Query
{
    projects
    {
        name,
        createdBy
    }
}

// Sample Result
{
  "data": {
    "projects": [
      {
        "name": "Migrate to TLS 1.2",
        "createdBy": "Giorgi"
      },
      {
        "name": "Move Blog to Hugo",
        "createdBy": "Giorgi"
      }
    ]
  }
}

Fields could have zero or more arguments. Arguments can be either optional or mandatory. In case of optional parameter, we define a default value.

type Person{
    id: Int!,
    name: String!,
    createdBy: String!,
    department:(departmentCode:Int = 1) : Department
}

As mentioned earlier, GraphQL is not limited to queries, but can also execute CRUD operations using mutations. The mutations can not only make modifications on the server, but can also return values.

mutation{
    createUser(name:String):Int
}

We have so far gone through the basic building blocks of GraphQL. There are still a few areas of interest like the fragment, but we will explore it as we progress further in the tutorial.

In the next part, we will use HotChocolate to implement GraphQL in .Net Web API. Until then, if you would like to read more on GraphQL, the official documentation is a great place to start with.